@phnx-labs/agents-cli 1.20.90 → 1.20.92

package/dist/lib/perf/spool.js

@@ -0,0 +1,79 @@
+/**
+ * Hot-path perf writers — append-only NDJSON spool, no SQLite.
+ *
+ * Loaded from the CLI root `postAction` and from `events.ts` timing helpers.
+ * Must stay free of `../sqlite.js` so ordinary commands never load node:sqlite
+ * (which emits ExperimentalWarning on stderr).
+ */
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { getPerfSpoolPath } from '../state.js';
+import { localMachineId } from '../session/origin-machine.js';
+let _spoolOverride = null;
+let _disabled = false;
+/** Test seam — pair with db._resetPerfDbForTest. */
+export function _resetPerfSpoolForTest(spoolPath) {
+    _spoolOverride = spoolPath === undefined ? null : spoolPath;
+    _disabled = false;
+}
+export function resolveSpoolPath() {
+    if (process.env.AGENTS_PERF_SPOOL)
+        return process.env.AGENTS_PERF_SPOOL;
+    if (_spoolOverride)
+        return _spoolOverride;
+    return getPerfSpoolPath();
+}
+function isDisabled() {
+    if (_disabled)
+        return true;
+    const v = process.env.AGENTS_DISABLE_PERF;
+    return v === '1' || v === 'true';
+}
+/** Short session id: first 8 chars (sessions.short_id shape). */
+export function shortSessionId(sessionId) {
+    if (!sessionId)
+        return undefined;
+    const cleaned = sessionId.replace(/^session_/, '');
+    return cleaned.length >= 8 ? cleaned.slice(0, 8) : cleaned || undefined;
+}
+/**
+ * Append one sample to the spool. Never throws. Never opens SQLite.
+ */
+export function recordSample(sample) {
+    if (isDisabled())
+        return;
+    if (!sample.label || !Number.isFinite(sample.durationMs))
+        return;
+    try {
+        const tsMs = sample.tsMs ?? Date.now();
+        const sessionId = sample.sessionId;
+        const sessionShort = sample.sessionShort ?? shortSessionId(sessionId);
+        const machine = sample.machine ?? localMachineId();
+        const hostname = sample.hostname ?? os.hostname();
+        const line = JSON.stringify({
+            ts_ms: tsMs,
+            kind: sample.kind,
+            label: sample.label,
+            duration_ms: sample.durationMs,
+            session_id: sessionId,
+            session_short: sessionShort,
+            agent: sample.agent,
+            agent_version: sample.agentVersion,
+            machine,
+            hostname,
+            actor: sample.actor,
+            cwd: sample.cwd,
+            cache: sample.cache,
+            exit_code: sample.exitCode,
+            status: sample.status,
+            meta_json: sample.metaJson,
+        });
+        const spool = resolveSpoolPath();
+        fs.mkdirSync(path.dirname(spool), { recursive: true, mode: 0o700 });
+        fs.appendFileSync(spool, line + '\n', { mode: 0o600 });
+    }
+    catch {
+        // Fail soft.
+    }
+}

package/dist/lib/perf/types.d.ts

@@ -0,0 +1,45 @@
+/** Shared perf sample shape (spool NDJSON + SQLite rows). */
+export type PerfKind = 'hook.fire' | 'perf.timing' | 'command.end' | string;
+export interface PerfSample {
+    tsMs?: number;
+    kind: PerfKind;
+    label: string;
+    durationMs: number;
+    /** Full session id — same string as sessions.id when known. */
+    sessionId?: string;
+    /** First 8 chars of sessionId (sessions.short_id shape). */
+    sessionShort?: string;
+    agent?: string;
+    agentVersion?: string;
+    /** Fleet registry name (sessions.machine), preferred over raw hostname. */
+    machine?: string;
+    hostname?: string;
+    actor?: string;
+    cwd?: string;
+    cache?: string;
+    exitCode?: number;
+    status?: string;
+    metaJson?: string;
+}
+export interface PerfAggregateRow {
+    kind: string;
+    label: string;
+    n: number;
+    p50Ms: number;
+    p99Ms: number;
+    meanMs: number;
+    maxMs: number;
+    minMs: number;
+    cacheHitPct?: number;
+    cacheStalePct?: number;
+    cacheMissPct?: number;
+    errorCount?: number;
+}
+export interface AggregateOptions {
+    days?: number;
+    kinds?: string[];
+    label?: string;
+    machine?: string;
+    agent?: string;
+    minN?: number;
+}

package/dist/lib/perf/types.js

@@ -0,0 +1,2 @@
+/** Shared perf sample shape (spool NDJSON + SQLite rows). */
+export {};

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;