@phnx-labs/agents-cli 1.22.119 → 1.22.121

package/dist/lib/projects.js

@@ -1,32 +1,3 @@
-/**
- * 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.
- *
- * That location makes definitions SYNCABLE, not automatically synced: they ride
- * the user repo only once they are committed to it, via `agents repo push user`
- * (`agents push` was removed). Until then the directory is untracked, and a
- * reconcile that cleans the working tree deletes it — observed twice on one
- * machine, taking four definitions with it each time. The recovery is an
- * orphaned `chore(local): save …-sync drift` commit, which is not a guarantee:
- * unreachable objects are collected. Say "commit them" rather than "for free".
- *
- * 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.
- */
 import * as fs from 'fs';
 import * as path from 'path';
 import * as yaml from 'yaml';
@@ -35,7 +6,6 @@ import { safeJoin } from './paths.js';
 import { toHomeRelative, expandLocalHome } from './project-root.js';
 import { resolveProjectKey } from './project-key.js';
 import { atomicWriteFileSync } from './fs-atomic.js';
-/** A project name safe to use as a filename: no separators, `..`, or leading dot. */
 export function isSafeProjectName(name) {
     return (typeof name === 'string' &&
         name.length > 0 &&
@@ -44,26 +14,17 @@ export function isSafeProjectName(name) {
         name !== '.' &&
         name !== '..');
 }
-/** Absolute path to a project's YAML definition. Throws on an unsafe name. */
 export function projectDefPath(name) {
     if (!isSafeProjectName(name)) {
         throw new Error(`Invalid project name: "${name}" (letters, digits, ., _, - only)`);
     }
     return safeJoin(getProjectsDir(), `${name}.yaml`);
 }
-/**
- * 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 function validateProjectDef(raw, sourceName) {
     if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
         throw new Error(`Project ${sourceName ?? ''} is not a YAML mapping`.trim());
     }
     const o = raw;
-    // The filename is the identity; a `name:` field is optional but, when present,
-    // must be a valid slug — a malformed one is a loud error, not a silent fallback.
     const hasNameField = 'name' in o && o.name !== undefined && o.name !== null;
     let name;
     if (hasNameField) {
@@ -78,8 +39,6 @@ export function validateProjectDef(raw, sourceName) {
     if (!name || !isSafeProjectName(name)) {
         throw new Error('Project definition is missing a valid "name"');
     }
-    // The filename IS the stable id — a def whose `name:` disagrees with its
-    // filename would resolve under one name and list under another.
     if (hasNameField && sourceName && name !== sourceName) {
         throw new Error(`Project ${sourceName}: "name" (${JSON.stringify(name)}) must match the filename — the filename is the stable id`);
     }
@@ -96,8 +55,6 @@ export function validateProjectDef(raw, sourceName) {
         def.repos = o.repos.flatMap((r) => {
             if (r && typeof r === 'object' && typeof r.slug === 'string') {
                 const rr = r;
-                // A malformed `path` sinks the whole entry, like any other malformed
-                // list row — a half-valid repo must not probe a surprising location.
                 if (rr.path !== undefined && typeof rr.path !== 'string')
                     return [];
                 const repo = { slug: rr.slug };
@@ -175,11 +132,6 @@ export function validateProjectDef(raw, sourceName) {
     }
     return def;
 }
-/**
- * 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 function loadProjectDef(name) {
     if (!isSafeProjectName(name))
         return undefined;
@@ -189,23 +141,15 @@ export function loadProjectDef(name) {
     }
     catch (error) {
         if (error.code === 'ENOENT') {
-            return undefined; // absent — not a defined project
+            return undefined;
         }
         throw error;
     }
     return validateProjectDef(yaml.parse(raw), name);
 }
-/**
- * List every defined project, sorted by name. A missing projects directory is
- * the empty state; malformed definitions and filesystem failures stay loud so
- * CLI callers (including Factory) can show the actual error.
- */
 export function listProjectDefs() {
     let files;
     try {
-        // Definitions are `<name>.yaml` (what projectDefPath/loadProjectDef read). We
-        // deliberately do NOT list `.yml` here — accepting it would then ENOENT in the
-        // loader and silently drop the project. One extension, one code path.
         files = fs.readdirSync(getProjectsDir()).filter((f) => f.endsWith('.yaml'));
     }
     catch (error) {
@@ -222,11 +166,6 @@ export function listProjectDefs() {
     }
     return out.sort((a, b) => a.name.localeCompare(b.name));
 }
-/**
- * Persist a project definition, normalizing `root`/`defaultPath` to home-relative
- * so it stays portable across machines. Creates the projects dir on first write.
- * Writes via temp+rename so readers never see a partial file.
- */
 export function writeProjectDef(def) {
     const validated = validateProjectDef(def, def.name);
     const normalized = {
@@ -242,14 +181,12 @@ export function writeProjectDef(def) {
             return repo;
         }),
     };
-    // Drop undefined keys so the YAML stays clean.
     const clean = Object.fromEntries(Object.entries(normalized).filter(([, v]) => v !== undefined));
     const target = projectDefPath(def.name);
     fs.mkdirSync(getProjectsDir(), { recursive: true });
     atomicWriteFileSync(target, yaml.stringify(clean), 'utf8');
     return target;
 }
-/** Delete a project definition. Returns true if a file was removed. Never touches the repo. */
 export function removeProjectDef(name) {
     try {
         fs.unlinkSync(projectDefPath(name));
@@ -261,36 +198,12 @@ export function removeProjectDef(name) {
         throw error;
     }
 }
-/**
- * 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 function projectBasePath(def, forRemote) {
     const base = def.defaultPath ?? def.root;
     if (!base)
         return undefined;
     return forRemote ? base : expandLocalHome(base);
 }
-/**
- * Every directory a project binds, ordered: `primary` first, then each
- * `repos[]` entry that carries a local `path` (joined with its `subpath`).
- * Deduped by resolved path, so a repo row pointing at the primary collapses.
- *
- * The repos[] walk and the dedupe are shared; the three things the two callers
- * genuinely disagree on are parameters rather than guesses, because collapsing
- * them would change one caller's meaning:
- *
- * - **primary** — spawning anchors on the cwd an agent lands in
- *   (`defaultPath ?? root`); probing anchors on `root`, so a monorepo
- *   subproject still probes its checkout rather than its subdirectory.
- * - **keepMissing** — probing KEEPS a missing directory, because reporting
- *   `✗ missing` across the fleet is the whole job. A local spawn drops it: a
- *   grant for a path that is not on this box is noise the harness rejects.
- * - **joinSubpath** — a spawn grants the subdirectory the project declares it
- *   cares about; a probe wants the repo root, since git status is a
- *   whole-checkout question.
- */
 function projectDirList(def, opts) {
     const raw = [
         opts.primary,
@@ -305,8 +218,6 @@ function projectDirList(def, opts) {
     const seen = new Set();
     const out = [];
     for (const p of raw) {
-        // Dedupe on the absolute local path so `~/src/x` and an already-expanded
-        // `/home/me/src/x` in a hand-edited def collapse to one entry.
         const abs = path.resolve(expandLocalHome(p));
         if (seen.has(abs))
             continue;
@@ -317,16 +228,6 @@ function projectDirList(def, opts) {
     }
     return out;
 }
-/**
- * All checkout targets for a project definition, each tagged with its expected
- * GitHub slug. The primary root carries `def.repo`; each `repos[i].path`
- * carries `repos[i].slug`. Paths are home-relative (re-root per fleet device)
- * and include missing checkouts so a remote peer can answer `missing` for them.
- *
- * This is the single authoritative expansion for both `projects status` (via
- * {@link projectProbeTargets}) and `projects pull`, so the two commands always
- * operate on exactly the same set of directories.
- */
 export function projectRepoTargetsForDef(def) {
     const targets = [];
     const seen = new Set();
@@ -345,29 +246,13 @@ export function projectRepoTargetsForDef(def) {
     }
     return targets;
 }
-/**
- * The directories `projects status` probes across the fleet: the repo root plus
- * every bound checkout, home-relative so each host re-roots them, and including
- * directories absent here so a peer can still answer `✗ missing` for them.
- */
 export function projectProbeTargets(def) {
     return projectRepoTargetsForDef(def).map((t) => t.path);
 }
-/**
- * The directories an agent spawned on this project should reach: the cwd first
- * (`resolveDefinedProjectPath`, so cwd behavior is unchanged), then every other
- * bound repo. `forRemote` keeps them `~/…` so the remote shell re-roots them at
- * its own `$HOME`; locally they are absolute and filtered to what exists.
- *
- * Callers pass the resolved primary so a `--project slug@worktree` run grants
- * the sibling repos alongside the worktree it actually landed in.
- */
 export function projectDirsAbs(def, opts) {
     return projectDirList(def, {
         primary: opts.primary ?? projectBasePath(def, opts.forRemote),
         forRemote: opts.forRemote,
-        // A remote spawn must not be filtered by THIS box's filesystem: the target
-        // host has its own checkouts, and a dir missing here may well be there.
         keepMissing: opts.forRemote,
         joinSubpath: true,
     });
@@ -380,49 +265,21 @@ function projectRootsAbs(defs) {
         out.push({ name, abs: path.resolve(expandLocalHome(raw)) });
     };
     for (const def of defs) {
-        // `root` says where the CHECKOUT is; `defaultPath` says which work is this
-        // project's. For a monorepo subproject those differ, and only the narrower
-        // one is a membership claim — a project scoped to `rush/apps/cli` does not
-        // own `rush/apps/web`.
-        //
-        // The old `root ?? defaultPath` collapsed such a subproject onto the
-        // monorepo root, the same path its umbrella anchors at, so the longest-match
-        // tiebreak below had nothing to separate them and a session in
-        // `rush/apps/cli` counted toward whichever definition was listed first.
         const rootAbs = def.root ? path.resolve(expandLocalHome(def.root)) : undefined;
         const defaultAbs = def.defaultPath ? path.resolve(expandLocalHome(def.defaultPath)) : undefined;
         const narrowed = !!(rootAbs && defaultAbs && defaultAbs !== rootAbs && isUnder(defaultAbs, rootAbs));
-        // A narrowed project's root is a WEAK claim: it still covers the rest of the
-        // checkout when nobody else wants it, but yields to any project that claims
-        // a path outright. Dropping it entirely regressed the single-project case —
-        // `add foo --root ~/src/foo --path apps/web` stopped attributing work
-        // anywhere else in its own repo, and `--path` means where agents START, not
-        // which work counts.
         if (rootAbs)
             out.push({ name: def.name, abs: rootAbs, weak: narrowed });
         if (defaultAbs && defaultAbs !== rootAbs)
             out.push({ name: def.name, abs: defaultAbs });
         for (const r of def.repos ?? []) {
             push(def.name, r.path);
-            // A repo pinned to a monorepo subpath anchors at that subpath too.
             if (r.path && r.subpath)
                 push(def.name, path.join(expandLocalHome(r.path), r.subpath));
         }
     }
     return out;
 }
-/**
- * The repository paths a project claims, as `{ slug, prefix }` with `prefix`
- * repo-relative and `dir/` shaped — the same ownership {@link projectRootsAbs}
- * applies to a session's cwd, expressed against the repository instead of a
- * checkout: a `defaultPath` narrowed under `root` claims that subtree of the
- * primary `repo`, and a `repos[]` entry with a `subpath` claims that subpath. A
- * project with no narrowed claim on a repository claims all of it and yields no
- * row for it. Two cases of {@link projectRootsAbs} have no repository form and
- * yield nothing here: a `defaultPath` outside `root` (no repo-relative path),
- * and the weak root of a narrowed project (it only takes what nobody claims,
- * which for a PR is the `repo-wide` scope).
- */
 export function repoPathClaims(def) {
     const out = [];
     const add = (slug, rel) => {
@@ -442,26 +299,12 @@ export function repoPathClaims(def) {
     }
     return out;
 }
-/** True when `child` is `parent` or nested under it (path-segment aware). */
 function isUnder(child, parent) {
     if (child === parent)
         return true;
     const withSep = parent.endsWith(path.sep) ? parent : parent + path.sep;
     return child.startsWith(withSep);
 }
-/**
- * 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 docs/concepts.md).
- */
 export function projectNameForCwd(cwd, defs) {
     if (!cwd)
         return undefined;
@@ -486,23 +329,6 @@ export function projectNameForCwd(cwd, defs) {
     }
     return best ?? weakBest;
 }
-/**
- * Definition list, memoized against a stamp over the definition FILES, for the
- * per-tick readers (PHNX-3999).
- *
- * {@link listProjectDefs} parses every `<name>.yaml`, which is the right cost for
- * a command but not for a row builder on the `feed watch` / `sessions watch`
- * stream — that runs twice a second for as long as an editor window is open (see
- * `AGENTS.md`, every tick is budgeted). One `readdir` plus one `stat` per
- * definition replaces N YAML parses.
- *
- * The stamp is each file's name + mtime + size, NOT the directory's mtime: editing
- * a definition in place — retargeting a project's `root`, which is exactly what
- * changes which sessions belong to it — moves the FILE's mtime and leaves the
- * directory's untouched, so a directory stamp would serve a stale association for
- * the life of the process. An unreadable directory is not cached: the next call
- * retries.
- */
 let projectDefsMemo = null;
 function projectDefsStamp() {
     try {
@@ -515,7 +341,6 @@ function projectDefsStamp() {
                 return `${f}:${st.mtimeMs}:${st.size}`;
             }
             catch {
-                // Removed between readdir and stat — its absence is part of the stamp.
                 return `${f}:gone`;
             }
         })
@@ -527,7 +352,6 @@ function projectDefsStamp() {
 }
 export function listProjectDefsCached() {
     const stamp = projectDefsStamp();
-    // No projects dir (or unreadable): nothing is confirmed, and nothing to cache.
     if (stamp === null)
         return [];
     if (projectDefsMemo && projectDefsMemo.stamp === stamp)
@@ -536,55 +360,19 @@ export function listProjectDefsCached() {
     projectDefsMemo = { stamp, defs };
     return defs;
 }
-/** Drop the {@link listProjectDefsCached} memo — for tests that rewrite the dir within one mtime tick. */
 export function resetProjectDefsCache() {
     projectDefsMemo = null;
 }
-/**
- * The **confirmed** project for a working directory, or `undefined` when the
- * association is not confirmed (PHNX-3999 F08/F09).
- *
- * Confirmed means exactly one thing: a registered project definition
- * ({@link projectNameForCwd}) whose root contains this path. Being inside *some*
- * git repository is NOT a project association — a repo nobody registered, a
- * checkout of someone else's code, or a loose directory that merely has a
- * `.git` in it would each invent a project name out of a folder, which is the
- * wrong-grouping the owner's recording shows at 01:30–01:56. So is a bare
- * directory basename ({@link resolveProjectKey}, which always answers).
- *
- * A consumer renders `undefined` as Uncategorized and keeps the session
- * reachable in its full list — nothing is hidden by not being grouped.
- *
- * Use {@link resolveProjectNameForCwd} instead when you want a best-effort
- * bucket KEY for joining rows; use this when the answer is shown to a person as
- * "this work belongs to that project".
- */
 export function confirmedProjectForCwd(cwd, defs = listProjectDefsCached()) {
     if (!cwd)
         return undefined;
     return projectNameForCwd(cwd, defs);
 }
-/**
- * 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 function resolveProjectNameForCwd(cwd, defs) {
     if (!cwd)
         return undefined;
     return projectNameForCwd(cwd, defs) ?? resolveProjectKey(cwd);
 }
-/**
- * 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 function resolveDefinedProjectPath(def, worktree, forRemote) {
     if (worktree) {
         const rootRaw = def.root ?? def.defaultPath;

package/dist/lib/pwsh.d.ts

@@ -1,44 +1,3 @@
-/**
- * PowerShell `-EncodedCommand` helper.
- *
- * Base64 of a script's UTF-16LE bytes is a single quote-free token, so it rides
- * through Node spawn → Windows sshd → cmd.exe with zero escaping hazards
- * (hand-quoted `powershell -Command "…"` is fragile the moment a path, URL, or
- * newline is involved). Shared by the browser SSH driver (which builds a
- * `powershell -EncodedCommand …` string) and the Windows secrets backend (which
- * spawns powershell.exe with an argv array).
- */
 export declare function encodePwshBase64(script: string): string;
-/** Single-quote a value for PowerShell's own parser (embedded `'` doubled). */
 export declare function pwshLiteral(value: string): string;
-/**
- * PowerShell statements that run a NATIVE program with exact argv.
- *
- * Windows has no argv array: a process receives ONE string and splits it itself.
- * PowerShell 5.1 rebuilds that string when it invokes a native program, and its
- * serializer is lossy — measured on a real peer, an EMPTY argument is dropped and
- * an embedded `"` is discarded. So the arguments are pre-escaped by the caller to
- * the `CommandLineToArgvW` rules (`quoteWin32ExecArg`) and handed to .NET as one
- * `Arguments` string, which `CreateProcess` receives essentially verbatim. No shell
- * is involved, so no `%VAR%` expansion and no newline sensitivity.
- *
- * `UseShellExecute = $false` with no redirection leaves the child on the inherited
- * handles, which is what lets a binary stdout stream through unchanged.
- *
- * `WorkingDirectory` is set explicitly from `(Get-Location).ProviderPath`, and that
- * is not belt-and-braces: PowerShell's `Set-Location` moves the SHELL's location
- * without updating the .NET process's OS working directory, so a child launched
- * through `ProcessStartInfo` would otherwise start in whatever directory the
- * process began in — silently ignoring a caller's `cwd` (`--remote-cwd`). The
- * `ProviderPath` form is what yields a real filesystem path rather than a
- * PowerShell provider path.
- *
- * @param fileNameExpr a PowerShell EXPRESSION for the executable (a quoted literal,
- *   or something like `$__c.Source`) — not a raw path, so a caller that resolved the
- *   target on the peer can pass its variable.
- * @param argumentsExpr a PowerShell EXPRESSION producing the argument string —
- *   `pwshLiteral(line)` for a static one, or a concatenation when part of it is
- *   only known on the peer (a resolved interpreter entry, say).
- * @param exitVar variable name for the child, so a caller can chain on it.
- */
 export declare function pwshNativeExecStatements(fileNameExpr: string, argumentsExpr: string, exitVar?: string): string[];

package/dist/lib/pwsh.js

@@ -1,67 +1,16 @@
-/**
- * PowerShell `-EncodedCommand` helper.
- *
- * Base64 of a script's UTF-16LE bytes is a single quote-free token, so it rides
- * through Node spawn → Windows sshd → cmd.exe with zero escaping hazards
- * (hand-quoted `powershell -Command "…"` is fragile the moment a path, URL, or
- * newline is involved). Shared by the browser SSH driver (which builds a
- * `powershell -EncodedCommand …` string) and the Windows secrets backend (which
- * spawns powershell.exe with an argv array).
- */
 export function encodePwshBase64(script) {
     return Buffer.from(script, 'utf16le').toString('base64');
 }
-/** Single-quote a value for PowerShell's own parser (embedded `'` doubled). */
 export function pwshLiteral(value) {
     return `'${value.replace(/'/g, "''")}'`;
 }
-/**
- * PowerShell statements that run a NATIVE program with exact argv.
- *
- * Windows has no argv array: a process receives ONE string and splits it itself.
- * PowerShell 5.1 rebuilds that string when it invokes a native program, and its
- * serializer is lossy — measured on a real peer, an EMPTY argument is dropped and
- * an embedded `"` is discarded. So the arguments are pre-escaped by the caller to
- * the `CommandLineToArgvW` rules (`quoteWin32ExecArg`) and handed to .NET as one
- * `Arguments` string, which `CreateProcess` receives essentially verbatim. No shell
- * is involved, so no `%VAR%` expansion and no newline sensitivity.
- *
- * `UseShellExecute = $false` with no redirection leaves the child on the inherited
- * handles, which is what lets a binary stdout stream through unchanged.
- *
- * `WorkingDirectory` is set explicitly from `(Get-Location).ProviderPath`, and that
- * is not belt-and-braces: PowerShell's `Set-Location` moves the SHELL's location
- * without updating the .NET process's OS working directory, so a child launched
- * through `ProcessStartInfo` would otherwise start in whatever directory the
- * process began in — silently ignoring a caller's `cwd` (`--remote-cwd`). The
- * `ProviderPath` form is what yields a real filesystem path rather than a
- * PowerShell provider path.
- *
- * @param fileNameExpr a PowerShell EXPRESSION for the executable (a quoted literal,
- *   or something like `$__c.Source`) — not a raw path, so a caller that resolved the
- *   target on the peer can pass its variable.
- * @param argumentsExpr a PowerShell EXPRESSION producing the argument string —
- *   `pwshLiteral(line)` for a static one, or a concatenation when part of it is
- *   only known on the peer (a resolved interpreter entry, say).
- * @param exitVar variable name for the child, so a caller can chain on it.
- */
 export function pwshNativeExecStatements(fileNameExpr, argumentsExpr, exitVar = '$zp') {
-    // Deliberately terse. The whole script is base64'd into ONE ssh command line,
-    // and OpenSSH-for-Windows caps that far below cmd.exe's 8191 — measured on a
-    // real peer, it fails between ~2.8k and ~4.1k characters. UTF-16LE + base64
-    // inflates by ~2.7x, so every character here costs almost three on the wire.
-    // `System.` is implicit for these types, and `-EA` is the canonical alias.
     return [
         `$zi=New-Object Diagnostics.ProcessStartInfo`,
         `$zi.FileName=${fileNameExpr}`,
         `$zi.Arguments=${argumentsExpr}`,
         `$zi.UseShellExecute=$false`,
         `$zi.WorkingDirectory=(Get-Location).ProviderPath`,
-        // The CALLER sets `$ErrorActionPreference='Stop'` for the whole script, so it
-        // is not repeated here — every character costs ~2.7 on the wire after base64.
-        // The null guard below is what makes a swallowed Start failure impossible to
-        // mistake for success: without it the handle is $null, the code is $null, and
-        // `exit $null` reports 0.
         `${exitVar}=[Diagnostics.Process]::Start($zi)`,
         `if($null -eq ${exitVar}){throw "start failed: $($zi.FileName)"}`,
         `${exitVar}.WaitForExit()`,

package/dist/lib/quick-todo.d.ts

@@ -0,0 +1,84 @@
+import type { ProjectDef } from './projects.js';
+export declare const QUICK_TODO_MARKER = "Created from AGI Menu";
+export declare const TODO_LIST_LIMIT = 6;
+export declare const UNDO_CREATE_WINDOW_MS = 30000;
+export type TodoPriority = 'urgent' | 'high';
+export declare const ADD_PRIORITIES: readonly ["urgent", "high", "medium", "low", "none"];
+export type AddPriority = (typeof ADD_PRIORITIES)[number];
+export declare const TITLE_MIN = 3;
+export declare const TITLE_MAX = 120;
+export declare const DESCRIPTION_MAX = 10000;
+export interface ParsedTodo {
+    title: string;
+    project: string | null;
+    due: string | null;
+    priority: TodoPriority | null;
+}
+export declare function localDay(date: Date): string;
+export declare function resolveDayWord(word: string, now: Date): string;
+export declare function parseQuickTodo(text: string, now: Date): ParsedTodo;
+export declare function linearProjectFor(token: string, defs: readonly ProjectDef[]): string;
+export interface QuickTodo {
+    identifier: string;
+    url: string | null;
+    title: string;
+    project: string | null;
+    due: string | null;
+    priority: number;
+    /** The workflow state's name (Todo, Doing, Done, …). */
+    state: string;
+    createdAt: string;
+    quick: boolean;
+}
+export type LinearExec = (args: string[]) => Promise<{
+    stdout: string;
+    stderr: string;
+}>;
+export declare const linearExec: LinearExec;
+export declare function linearFailure(err: unknown): string;
+type RawIssue = {
+    identifier?: string;
+    url?: string;
+    title?: string;
+    description?: string | null;
+    dueDate?: string | null;
+    priority?: number;
+    createdAt?: string;
+    project?: {
+        name?: string;
+    } | null;
+    state?: {
+        name?: string;
+    } | null;
+};
+export declare function toQuickTodo(issue: RawIssue): QuickTodo;
+export interface TodoResult {
+    ok: boolean;
+    todo: QuickTodo | null;
+    message: string;
+}
+export interface AddOptions {
+    project?: string;
+    description?: string;
+    assignee?: string;
+    due?: string;
+    priority?: AddPriority;
+    defs: readonly ProjectDef[];
+    now: Date;
+}
+export declare function addRefusal(title: string, opts: AddOptions): string | null;
+export declare function addQuickTodo(text: string, opts: AddOptions, linear?: LinearExec): Promise<TodoResult>;
+export declare function listQuickTodos(now: Date, linear?: LinearExec): Promise<{
+    todos: QuickTodo[];
+    total: number;
+}>;
+export declare const DONE_PROOF = "Checked off in AGI Menu";
+export declare function completeTodo(id: string, linear?: LinearExec): Promise<TodoResult>;
+/**
+ * Undo the last menu action on an issue: a completed one goes back to Todo; a
+ * quick to-do still open and created within {@link UNDO_CREATE_WINDOW_MS} is
+ * canceled (moved to the team's canceled state). Anything else is refused, so an
+ * Undo never silently does nothing.
+ */
+export declare function undoTodo(id: string, now: Date, linear?: LinearExec): Promise<TodoResult>;
+export {};