@phnx-labs/agents-cli 1.20.91 → 1.20.92

package/dist/lib/devices/registry.d.ts

@@ -80,6 +80,20 @@ export interface DeviceProfile {
 export declare function deviceRole(d: DeviceProfile): DeviceRole;
 /** True for a control-only device (a cockpit) that must never be dialed/scheduled. */
 export declare function isControlDevice(d: DeviceProfile): boolean;
+/**
+ * Whether a fan-out should dial this device, honouring the preference stated on
+ * {@link DeviceProfile.reachability}: the live SSH probe wins over the cached
+ * {@link DeviceTailscale.online} snapshot.
+ *
+ * Reading only `tailscale.online` is wrong in both directions, and both were
+ * live on a real fleet. A `via:"manual"` device never gets a tailscale peer
+ * entry at all, so its `online` is permanently `undefined` and a strict
+ * `=== true` test skipped it forever — every session on that box was invisible
+ * to the cross-fleet sweep. Conversely a box that has since gone to sleep keeps
+ * a stale `online:true` and gets dialed, burning a full ConnectTimeout and
+ * reporting a false "unreachable" that callers treat as doubt.
+ */
+export declare function isDialableDevice(d: DeviceProfile): boolean;
 /** Map of device name to profile. */
 export type DeviceRegistry = Record<string, DeviceProfile>;
 /** Throw if `name` is not usable as an ssh alias (no spaces, quotes, etc.). */

package/dist/lib/devices/registry.js

@@ -27,6 +27,43 @@ export function deviceRole(d) {
 export function isControlDevice(d) {
     return deviceRole(d) === 'control';
 }
+/**
+ * Whether a fan-out should dial this device, honouring the preference stated on
+ * {@link DeviceProfile.reachability}: the live SSH probe wins over the cached
+ * {@link DeviceTailscale.online} snapshot.
+ *
+ * Reading only `tailscale.online` is wrong in both directions, and both were
+ * live on a real fleet. A `via:"manual"` device never gets a tailscale peer
+ * entry at all, so its `online` is permanently `undefined` and a strict
+ * `=== true` test skipped it forever — every session on that box was invisible
+ * to the cross-fleet sweep. Conversely a box that has since gone to sleep keeps
+ * a stale `online:true` and gets dialed, burning a full ConnectTimeout and
+ * reporting a false "unreachable" that callers treat as doubt.
+ */
+export function isDialableDevice(d) {
+    // Union, deliberately: either signal saying "go" is enough. A probe may only
+    // ADD a peer to the sweep, never remove one.
+    //
+    // The probe is not trustworthy enough to exclude on. It runs with a short SSH
+    // budget, so on a congested tailnet it returns false negatives — observed
+    // marking the LOCAL machine unreachable, and flipping a live worker box from
+    // reachable to unreachable nine minutes apart. Letting that shrink the sweep
+    // would hide sessions on healthy boxes, a worse failure than the one below.
+    //
+    // The snapshot alone is not enough either: a device registered with
+    // `address.via: "manual"` never gets a tailscale peer entry, so `online`
+    // stays undefined and a strict `=== true` test skipped it forever, making
+    // every session on that box unresolvable from any other machine.
+    //
+    // So: no tailscale block at all is unknown-not-offline (the rule `ssh.ts`
+    // renderDeviceTable and Factory's `isDeviceOnline` already use, so the picker
+    // and the sweep agree on who exists), and a positive probe rescues a device
+    // whose snapshot says offline. The cost of dialing a box that is actually
+    // asleep is one ConnectTimeout — the pre-existing behaviour, not a regression.
+    if (d.reachability?.reachable)
+        return true;
+    return !d.tailscale || d.tailscale.online === true;
+}
 function registryPath() {
     return getDevicesRegistryPath();
 }

package/dist/lib/feed-post.js

@@ -15,7 +15,8 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { spawnSync } from 'child_process';
-import { appendActivityEvent, projectFromCwd, } from './activity.js';
+import { appendActivityEvent, } from './activity.js';
+import { resolveProjectNameForCwd, listProjectDefs } from './projects.js';
 import { getHistoryDir } from './state.js';
 import { machineId } from './machine-id.js';
 import { isValidMailboxId } from './mailbox.js';
@@ -263,7 +264,12 @@ export function postFeedStatus(input) {
             + '(AGENT_SESSION_ID / AGENTS_MAILBOX_DIR / pid registry), or pass --session <id>.');
     }
     const ts = input.ts ?? new Date().toISOString();
-    const project = projectFromCwd(identity.cwd);
+    // The post is written where the agent runs, so the cwd is a local path and
+    // gets full canonical resolution — a defined project's name wins (a post from
+    // any repo of a multi-repo project files under that project), else the repo
+    // key, matching how the timeline groups everything else. listProjectDefs is
+    // fail-open, so this costs one small readdir + YAML parse per post.
+    const project = resolveProjectNameForCwd(identity.cwd, listProjectDefs());
     const attachments = buildAttachments(input.attach, {
         copyRoot: input.attachmentsRoot ?? path.join(getHistoryDir(), 'attachments'),
         sessionId: identity.sessionId,

package/dist/lib/hosts/remote-cmd.js

@@ -88,6 +88,7 @@ export const RUN_OPTION_FORWARDING = {
     autoSecrets: 'forward', // workflow frontmatter secrets resolve on the REMOTE keychain
     emitSessionId: 'forward', // remote prints its session id as a stdout sentinel the launcher captures (session-marker.ts)
     // rejected — cannot cross the SSH boundary; fail loud, never degrade
+    terminal: 'reject', // opens a tab on THIS machine's desktop; a remote tab is a different request
     secrets: 'reject',
     secretsKeys: 'reject',
     allowExpired: 'reject',
@@ -126,6 +127,9 @@ export const RUN_OPTION_FORWARDING = {
 };
 /** Actionable messages for value-aware rejections, keyed by attribute name. */
 export const RUN_OPTION_REJECT_MESSAGES = {
+    terminal: '--terminal opens a tab on THIS machine; it cannot be combined with --host. ' +
+        'Drop --terminal to dispatch to the host, or drop --host to open the tab here. ' +
+        'To watch a remote run in a terminal, dispatch it and follow with `agents sessions focus <id>`.',
     secrets: '--secrets cannot cross the SSH boundary — Keychain values are never sent to a host implicitly. ' +
         'Provision the bundle on the host first (agents secrets export --host <name>), then run without --secrets; ' +
         'workflow frontmatter secrets resolve from the HOST\'s own keychain.',

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/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);
+}

package/dist/lib/project-root.js

@@ -17,6 +17,7 @@ import * as fs from 'fs';
 import { readMeta, updateMeta } from './state.js';
 import { getMainRepoRoot } from './git.js';
 import { toPosix } from './platform/index.js';
+import { loadProjectDef, resolveDefinedProjectPath } from './projects.js';
 const HOME = process.env.HOME ?? os.homedir();
 /** Rewrite an absolute path under the local home to a `~/`-relative string; pass others through. */
 export function toHomeRelative(abs) {
@@ -124,6 +125,21 @@ export function buildProjectPath(root, ref, forRemote) {
  * absolute local path and verifies it exists (so a mistyped slug fails loudly).
  */
 export async function resolveProjectRef(ref, opts) {
+    const { slug, worktree } = parseProjectRef(ref);
+    if (!slug)
+        throw new Error(`Invalid --project value: "${ref}"`);
+    // Definition first: a named project in ~/.agents/projects/<slug>.yaml overrides
+    // the <root>/<slug> convention. Absent (or root-less) → fall through unchanged.
+    const def = loadProjectDef(slug);
+    if (def) {
+        const fromDef = resolveDefinedProjectPath(def, worktree, opts.forRemote);
+        if (fromDef) {
+            if (!opts.forRemote && !fs.existsSync(fromDef)) {
+                throw new Error(`Project path not found: ${fromDef} (defined in ${slug}.yaml)`);
+            }
+            return fromDef;
+        }
+    }
     const cwd = opts.cwd ?? process.cwd();
     const root = await ensureProjectRoot(cwd);
     const resolved = buildProjectPath(root, ref, opts.forRemote);

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

@@ -0,0 +1,69 @@
+/**
+ * Project-level progress rollup — the headline of the projects subsystem.
+ *
+ * At 50–100 agents the per-agent activity line is noise; what matters is the
+ * PROJECT. This aggregates the signals already carried per session (status,
+ * plan progress, open PRs, tickets, worktrees) into one row per project, keyed
+ * by matching each session's cwd to a defined project root (`projectNameForCwd`).
+ * The session set is whatever the caller passes (today `getActiveSessions()` —
+ * this machine's live view, matched by local-home cwd; a fleet-wide fan-out is a
+ * deferred follow-up). Pure over an `ActiveSession[]` so the aggregation is
+ * unit-testable; the merged-PR signal IS repo-global (harvested via `gh`) and the
+ * artifact signal is local, both added in `enrichProjectSignals`.
+ */
+import type { ActiveSession, ActiveStatus } from './session/active.js';
+import { type ProjectDef } from './projects.js';
+/** One project's live session rollup. */
+export interface ProjectSessionRollup {
+    name: string;
+    /** Total sessions whose cwd is inside this project. */
+    agents: number;
+    /** Count per lifecycle status. */
+    byStatus: Partial<Record<ActiveStatus, number>>;
+    /** Summed checklist progress across this project's sessions. */
+    plan: {
+        done: number;
+        total: number;
+    };
+    /** Distinct open PRs held by this project's sessions. */
+    openPrs: {
+        url: string;
+        number?: number;
+    }[];
+    /** Distinct tickets worked or created by this project's sessions. */
+    tickets: string[];
+    /** Sessions running inside a worktree. */
+    worktrees: number;
+}
+/**
+ * Roll active sessions up by project. Returns a map keyed by project name,
+ * containing only projects with at least one matched session — callers merge
+ * with the full definition list to show zero-agent projects.
+ */
+export declare function rollupSessionsByProject(defs: ProjectDef[], sessions: ActiveSession[]): Map<string, ProjectSessionRollup>;
+/** Plan completion percentage (0–100), or undefined when nothing is tracked. */
+export declare function planPct(plan: {
+    done: number;
+    total: number;
+}): number | undefined;
+/** Harvested signals not on the session list: repo-global merged PRs + local artifacts, in a time window. */
+export interface ProjectRemoteSignals {
+    windowDays: number;
+    /** PRs merged into the primary repo within the window (via `gh`). */
+    mergedPrs: number;
+    /** Artifacts agents produced within the window (activity.created milestones). */
+    artifacts: number;
+    /** Basename of the most recent artifact, when any. */
+    lastArtifact?: string;
+}
+/**
+ * Harvest the signals that don't live on the active-session list: recently
+ * merged PRs (from GitHub via `gh`) and artifacts agents produced (from the
+ * local activity-milestone log, matched to the project by cwd). Best-effort —
+ * a missing `gh`, no auth, or no repo degrades to zero rather than throwing, so
+ * `projects status` still renders. `nowMs` is injected for testability.
+ */
+export declare function enrichProjectSignals(def: ProjectDef, windowDays: number, nowMs: number, opts?: {
+    activityRoot?: string;
+    skipRemote?: boolean;
+}): Promise<ProjectRemoteSignals>;

package/dist/lib/project-status.js

@@ -0,0 +1,101 @@
+/**
+ * Project-level progress rollup — the headline of the projects subsystem.
+ *
+ * At 50–100 agents the per-agent activity line is noise; what matters is the
+ * PROJECT. This aggregates the signals already carried per session (status,
+ * plan progress, open PRs, tickets, worktrees) into one row per project, keyed
+ * by matching each session's cwd to a defined project root (`projectNameForCwd`).
+ * The session set is whatever the caller passes (today `getActiveSessions()` —
+ * this machine's live view, matched by local-home cwd; a fleet-wide fan-out is a
+ * deferred follow-up). Pure over an `ActiveSession[]` so the aggregation is
+ * unit-testable; the merged-PR signal IS repo-global (harvested via `gh`) and the
+ * artifact signal is local, both added in `enrichProjectSignals`.
+ */
+import { execFile } from 'child_process';
+import { promisify } from 'util';
+import { projectNameForCwd } from './projects.js';
+import { readRecentActivity } from './activity.js';
+const execFileAsync = promisify(execFile);
+function blank(name) {
+    return { name, agents: 0, byStatus: {}, plan: { done: 0, total: 0 }, openPrs: [], tickets: [], worktrees: 0 };
+}
+/**
+ * Roll active sessions up by project. Returns a map keyed by project name,
+ * containing only projects with at least one matched session — callers merge
+ * with the full definition list to show zero-agent projects.
+ */
+export function rollupSessionsByProject(defs, sessions) {
+    const map = new Map();
+    const prSeen = new Map();
+    const ticketSeen = new Map();
+    for (const s of sessions) {
+        const name = projectNameForCwd(s.cwd, defs);
+        if (!name)
+            continue;
+        let r = map.get(name);
+        if (!r) {
+            r = blank(name);
+            map.set(name, r);
+            prSeen.set(name, new Set());
+            ticketSeen.set(name, new Set());
+        }
+        r.agents++;
+        r.byStatus[s.status] = (r.byStatus[s.status] ?? 0) + 1;
+        if (s.todos) {
+            r.plan.done += s.todos.done;
+            r.plan.total += s.todos.total;
+        }
+        if (s.pr?.url && !prSeen.get(name).has(s.pr.url)) {
+            prSeen.get(name).add(s.pr.url);
+            r.openPrs.push({ url: s.pr.url, number: s.pr.number });
+        }
+        const tset = ticketSeen.get(name);
+        for (const t of [s.ticket?.id, ...(s.createdTickets ?? [])]) {
+            if (t && !tset.has(t)) {
+                tset.add(t);
+                r.tickets.push(t);
+            }
+        }
+        if (s.worktree)
+            r.worktrees++;
+    }
+    return map;
+}
+/** Plan completion percentage (0–100), or undefined when nothing is tracked. */
+export function planPct(plan) {
+    if (plan.total <= 0)
+        return undefined;
+    return Math.round((plan.done / plan.total) * 100);
+}
+/**
+ * Harvest the signals that don't live on the active-session list: recently
+ * merged PRs (from GitHub via `gh`) and artifacts agents produced (from the
+ * local activity-milestone log, matched to the project by cwd). Best-effort —
+ * a missing `gh`, no auth, or no repo degrades to zero rather than throwing, so
+ * `projects status` still renders. `nowMs` is injected for testability.
+ */
+export async function enrichProjectSignals(def, windowDays, nowMs, opts = {}) {
+    const sinceMs = nowMs - windowDays * 86_400_000;
+    const out = { windowDays, mergedPrs: 0, artifacts: 0 };
+    try {
+        const evs = readRecentActivity({ events: ['artifact.created'], sinceMs, root: opts.activityRoot });
+        const mine = evs.filter((e) => projectNameForCwd(e.cwd, [def]) === def.name);
+        out.artifacts = mine.length;
+        if (mine.length && typeof mine[0].detail === 'string')
+            out.lastArtifact = mine[0].detail;
+    }
+    catch {
+        /* activity log unreadable — best-effort */
+    }
+    if (def.repo && !opts.skipRemote) {
+        try {
+            const { stdout } = await execFileAsync('gh', ['pr', 'list', '--repo', def.repo, '--state', 'merged', '--json', 'number,mergedAt', '--limit', '100'], { timeout: 8000, encoding: 'utf8' });
+            const rows = JSON.parse(stdout);
+            out.mergedPrs = rows.filter((r) => r.mergedAt && Date.parse(r.mergedAt) >= sinceMs).length;
+        }
+        catch {
+            /* gh missing / unauthenticated / repo not found — skip this signal */
+        }
+    }
+    return out;
+}

package/dist/lib/projects.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Named project definitions — the layer above the `--project <slug>` convention.
+ *
+ * `agents run --project <slug>` already resolves a bare name to a working
+ * directory by pure convention (`<projectRoot>/<slug>`, see `project-root.ts`).
+ * This module adds editable definitions on top: one YAML file per project under
+ * `~/.agents/projects/<name>.yaml`, sitting beside the existing `routines/`,
+ * `monitors/`, and `teams/` dirs in the user repo (so definitions sync across
+ * machines for free via `agents push/pull`). A defined project can name itself
+ * independently of its folder, bind more than one repo, pin a monorepo subpath,
+ * describe context subdirectories an agent should start from, carry a Linear
+ * link and external integrations, and set an explicit default path.
+ *
+ * Portable by construction: `root`/`defaultPath` are stored home-relative
+ * (`~/…`) via `toHomeRelative`, so the same definition re-roots on any machine
+ * whose home differs — the exact mechanism `project-root.ts` already relies on.
+ *
+ * Resolution stays additive: an undefined slug still resolves exactly as today
+ * (see `resolveProjectRef`), a defined one overrides it.
+ */
+/** A git repo bound to a project, with an optional monorepo subpath. */
+export interface ProjectRepo {
+    /** GitHub slug `owner/repo`. */
+    slug: string;
+    /** Optional path within the repo an agent working this project cares about. */
+    subpath?: string;
+}
+/**
+ * A described context anchor: a subdirectory plus what it is. Agents starting on
+ * the project read `purpose` to know where to look — an indexed starting point,
+ * not just a path. This is the richer form of the single monorepo-focus dir.
+ */
+export interface ProjectContext {
+    /** Path relative to the project root (e.g. `apps/web`). */
+    path: string;
+    /** One line on how this subtree relates to the project. */
+    purpose: string;
+}
+/** An external context source hung off the project (surfaced in `projects show`). */
+export interface ProjectIntegration {
+    /** e.g. `gdrive`, `notion`, `figma`, `url`. */
+    kind: string;
+    url: string;
+    label?: string;
+}
+/** The parsed `~/.agents/projects/<name>.yaml`. */
+export interface ProjectDef {
+    /** Stable id; matches the filename; what `--project` takes. */
+    name: string;
+    description?: string;
+    /** Repo / monorepo root, home-relative for portability. */
+    root?: string;
+    /** Where an agent's cwd lands. Defaults to `root` when unset. */
+    defaultPath?: string;
+    /** Primary GitHub slug (`owner/repo`) — for PR / CI / status roll-up. */
+    repo?: string;
+    /** All bound repos, each with an optional monorepo subpath. */
+    repos?: ProjectRepo[];
+    /** Described starting points inside the project. */
+    contexts?: ProjectContext[];
+    /** External context sources (Drive, docs, …). */
+    integrations?: ProjectIntegration[];
+    /** Linear project link — reuses the existing GraphQL path. */
+    linear?: {
+        projectId?: string;
+        url?: string;
+    };
+    /** Free-form doc links surfaced in `projects show`. */
+    docs?: string[];
+}
+/** A project name safe to use as a filename: no separators, `..`, or leading dot. */
+export declare function isSafeProjectName(name: string): boolean;
+/** Absolute path to a project's YAML definition. Throws on an unsafe name. */
+export declare function projectDefPath(name: string): string;
+/**
+ * Validate a raw parsed object into a `ProjectDef`, throwing an actionable error
+ * on the first problem. A malformed document or identity (bad/mismatched name)
+ * throws; malformed entries inside the optional lists (`repos`/`contexts`/
+ * `integrations`) are dropped so one bad row can't sink an otherwise good def.
+ */
+export declare function validateProjectDef(raw: unknown, sourceName?: string): ProjectDef;
+/**
+ * Load a single project definition by name. Returns undefined when the file is
+ * absent (the common "not a defined project, fall back to convention" case) but
+ * throws when a file EXISTS and is malformed — a broken definition is loud.
+ */
+export declare function loadProjectDef(name: string): ProjectDef | undefined;
+/**
+ * List every defined project, sorted by name. Skips (does not throw on) a
+ * malformed file so one bad definition can't break `projects list`; the loader
+ * for a single named project stays strict.
+ */
+export declare function listProjectDefs(): ProjectDef[];
+/**
+ * Persist a project definition, normalizing `root`/`defaultPath` to home-relative
+ * so it stays portable across machines. Creates the projects dir on first write.
+ */
+export declare function writeProjectDef(def: ProjectDef): string;
+/** Delete a project definition. Returns true if a file was removed. Never touches the repo. */
+export declare function removeProjectDef(name: string): boolean;
+/**
+ * The cwd an agent lands in for a defined project: `defaultPath` when set, else
+ * `root`. Home-relative when `forRemote` (the remote shell expands `~`), else
+ * expanded against the local home. Returns undefined when neither is set.
+ */
+export declare function projectBasePath(def: ProjectDef, forRemote: boolean): string | undefined;
+/**
+ * Which defined project a session belongs to, derived from its working
+ * directory. A session whose `cwd` sits inside a project's repo root (or a
+ * worktree under it) is a member; the LONGEST matching root wins so a nested
+ * project beats its parent. Returns undefined when no definition contains the
+ * path.
+ *
+ * The comparison is against the LOCAL home: roots and the cwd are both expanded
+ * with `expandLocalHome` and resolved, so this matches sessions whose cwd shares
+ * this machine's home layout. A session recorded on a different-home machine
+ * (`/Users/x/…` vs `/home/x/…`) will not match until the fleet-wide,
+ * home-relative variant lands (see the deferred item in docs/11-projects.md).
+ */
+export declare function projectNameForCwd(cwd: string | undefined, defs: ProjectDef[]): string | undefined;
+/**
+ * The canonical project label for a cwd, for every surface that buckets work by
+ * project (the activity timeline, feed posts, the sessions overview): the
+ * DEFINED project whose root contains the cwd (longest root wins, so a
+ * multi-repo project reads as one bucket), else the repository-level key from
+ * {@link resolveProjectKey}. `defs` comes from {@link listProjectDefs}, which is
+ * fail-open — with no definitions this degrades to exactly today's behavior.
+ */
+export declare function resolveProjectNameForCwd(cwd: string | undefined | null, defs: ProjectDef[]): string | undefined;
+/**
+ * Resolve a defined project's ref to a working directory, mirroring
+ * `buildProjectPath`'s `forRemote` contract (a home-relative `~/…` for the
+ * remote shell to expand, an absolute local path otherwise). A `@worktree`
+ * lands under the repo ROOT's `.agents/worktrees/`, not the `defaultPath`
+ * subdir — worktrees are per-repo, not per-focus. Returns undefined when the
+ * definition carries no `root`/`defaultPath` (caller falls back to convention).
+ */
+export declare function resolveDefinedProjectPath(def: ProjectDef, worktree: string | undefined, forRemote: boolean): string | undefined;