@phnx-labs/agents-cli 1.22.120 → 1.22.121

package/dist/commands/factory.d.ts

@@ -1,8 +1,2 @@
-/**
- * Software Factory CLI — submits Linear issues to a remote orchestrator.
- *
- * Requires FACTORY_FLOOR_URL pointing at a Factory-compatible endpoint.
- * Beta-gated; enable with `agents setup beta enable factory`.
- */
 import type { Command } from 'commander';
 export declare function registerFactoryCommands(program: Command): void;

package/dist/commands/factory.js

@@ -55,7 +55,6 @@ Examples:
   agents factory snapshot --json
 `);
     factory.hook('preAction', (_thisCommand, actionCommand) => {
-        // Foreman must be able to read its tick input before any beta-gated action.
         if (enabled || actionCommand.name() === 'snapshot')
             return;
         console.error(chalk.red('agents factory is in beta.'));
@@ -84,7 +83,6 @@ Examples:
             console.log(JSON.stringify(result, null, 2));
             return;
         }
-        // Register locally so `agents cloud logs <id>` can find it.
         const now = new Date().toISOString();
         insertTask({
             id: result.cloud_execution_id,

package/dist/commands/feed-watch.js

@@ -1,20 +1,6 @@
 import { setHelpSections } from '../lib/help.js';
 import { streamFeedFromHub, waitForHub } from '../lib/feed/hub-server.js';
 import { ensureDaemonStarted } from '../lib/daemon/daemon.js';
-/**
- * Attach to the daemon's shared collector, starting the daemon if it is not up.
- *
- * There is deliberately no in-process fallback: running `watchFleetFeed` here
- * would give this reader its own ssh child per peer, which is exactly the
- * per-caller fan-out the hub exists to collapse (see `lib/feed/hub.ts`). So a
- * missing hub is answered by starting its owner and WAITING for it.
- *
- * The wait is what makes that honest. `ensureDaemonStarted()` returns once the
- * process is spawned, long before it has loaded its services and bound the
- * socket, so retrying immediately raced the bind and reported a daemon that was
- * about to be perfectly healthy as unavailable. The final error is the one from
- * the last real attempt, not the first.
- */
 async function attachToHub(signal, emit, scope) {
     try {
         await streamFeedFromHub({ signal, emit, scope });
@@ -56,12 +42,6 @@ export function registerFeedWatchCommand(parent) {
         process.once('SIGINT', stop);
         process.once('SIGTERM', stop);
         try {
-            // BOTH scopes go through the daemon's shared collectors. `--local` used to
-            // run its own `watchLocalFeed`, so every observing box's ssh subscription
-            // built a separate activity cursor set, tool watcher and setup subscription
-            // on the SAME peer. The local collector is a distinct hub from the fleet one
-            // (`feed-stream-service.ts`) and its watcher dials no peer at all, so a
-            // local reader can never trigger a fan-out, recursively or otherwise.
             await attachToHub(controller.signal, emit, opts.local ? 'local' : 'fleet');
         }
         finally {

package/dist/commands/feed.d.ts

@@ -1,32 +1,12 @@
-/**
- * `agents feed` -- operator inbox + agent status posts.
- *
- * Default (`agents feed`): list open blocks (decisions agents are waiting on).
- * Aggregates block records from the local feed store and, with --device, from
- * reachable remote hosts via SSH passthrough. Each block carries enough
- * identity for `agents message` to route a reply back to the right agent.
- *
- * Default view groups by **outcome** (ticket / PR / worktree / Unassigned) so
- * an operator sees dozens of deliverables, not ~1,100 agents. Pass `--flat`
- * for the legacy per-agent list.
- *
- * `agents feed post`: agent-callable free-text progress into the activity
- * stream (milestone `status.posted`). Session/agent/host/runtime/pid identity
- * is auto-stamped from env + the pid registry — no domain-specific flags.
- * Humans watch via the feed activity lane.
- */
 import type { Command } from 'commander';
 import { type OpenBlock } from '../lib/feed/feed.js';
 import { type OutcomeGroup, type SessionOutcomeHint } from '../lib/feed-outcome.js';
 import { filterBlocksForFeed } from '../lib/ask-classifier.js';
 import { type FeedSessionSignal } from '../lib/feed-ranking.js';
 export declare const FEED_POST_HELP = "\nExamples:\n  # Title (subject) + body. Phone broadcasts put title first, body after a\n  # blank line, then a \"Sent from agent/session on host\" footer.\n  agents feed post --title \"CHANGELOG pushed\" \"Watching CI and mac-mini E2E\"\n  agents feed post --title \"Cover ready\" \"render at ./out/cover.png\" --attach ./out/cover.png\n  agents feed post --title \"Ready for review\" \"PR opened, waiting on prix-cloud\" --json\n\n  # Worth interrupting someone over - reaches sinks gated on minLevel: important:\n  agents feed post --title \"npm token expired\" \"Cannot publish the release\" --level important\n\n  # Also raise a local desktop banner on THIS machine (same notifier as run\n  # --notify), on top of any configured broadcast - useful when you are at the box:\n  agents feed post --title \"Build green\" \"all checks passed\" --notify\n\n  # Stuck: opens a needs-you block and always broadcasts at important:\n  agents feed post --title \"Force-push denied\" \"git-guard blocked PR #1749\" --blocked\n  agents feed post --title \"Publish or wait?\" \"npm publish now or after review\" --blocked --option publish --option wait\n  agents feed post --title \"Delete preview env?\" \"stale preview still running\" --blocked --default \"leave it\"\n\n  # Exhaust self-serve FIRST. A block is for what you genuinely cannot do:\n  # a credential only the user holds, a decision only they can make, an\n  # approval only they can give. Not \"should I do the obvious next step?\".\n\n  # Outside a run, pass the session explicitly:\n  agents feed post --title \"Manual note\" \"context for the next agent\" --session 00998b0e-2d15-4d2f-a58b-974a886c9b47\n\nIdentity (session, agent, host, runtime, pid, launchId) is stamped automatically\nand rides the phone footer of feed.broadcast {message}. Domain facts (tickets,\nPRs) are not CLI flags - the ticket is joined from the session index at post\ntime. No em-dashes in title/body - they are scrubbed on the way out.\n\nConfigure where a post is mirrored under feed.broadcast in agents.yaml - see\ndocs/observability.md. A channel sink may set message: with placeholders such\nas {message} and {ticket}; a missing placeholder skips that sink. A milestone is always recorded, but it does not text\nthe owner when the sink has minLevel: important. Add --level important for a\nphone-worthy successful update. Use --blocked only when work cannot continue.\nThe owner destination comes from humans.yaml; do not duplicate it in agents.yaml.\n";
-/** Right-hand masthead summary: `N blocks · M agents`. */
 export declare function formatFeedMastheadRight(blocks: OpenBlock[]): string;
-/** Reply hint matching the shared fleet-comms reply line. */
 export declare function formatFeedReplyHint(mailboxId: string): string;
 export declare function parseRemoteFeed(stdout: string, machine: string): OpenBlock[];
-/** Merge local and remote rows, keeping the first copy of a host/session block. */
 export declare function mergeFeedBlocks(...groups: OpenBlock[][]): OpenBlock[];
 type FeedControlAction = 'pause' | 'kill';
 export declare function controlFeedSession(action: FeedControlAction, target: string, signals: FeedSessionSignal[]): Promise<string>;
@@ -41,11 +21,8 @@ export declare function prepareLocalFeedBlocks(localBlocks: OpenBlock[], opts: {
     dispatch: OpenBlock[];
     filter: ReturnType<typeof filterBlocksForFeed>;
 };
-/** Specific host app + routine provenance for one feed row. */
 export declare function formatFeedRuntime(block: Pick<OpenBlock, 'runtime' | 'origin' | 'routineName'>): string;
-/** Human summary line for one outcome rollup. */
 export declare function formatOutcomeHeader(group: OutcomeGroup): string;
-/** Map active sessions into the lightweight hints outcome enrichment needs. */
 export declare function sessionHintsFromActive(sessions: Array<{
     sessionId?: string;
     agentId?: string;
@@ -64,27 +41,12 @@ export declare function sessionHintsFromActive(sessions: Array<{
     origin?: 'cli' | 'routine';
     routineName?: string;
 }>): SessionOutcomeHint[];
-/**
- * True when a SQLite open/query failed because another writer holds the lock.
- * better-sqlite3 surfaces this as message "database is locked" and/or code
- * SQLITE_BUSY (RUSH-2006).
- */
 export declare function isSqliteBusyError(err: unknown): boolean;
-/**
- * Load session metas for feed outcome enrichment. The sessions index can be
- * locked by a concurrent scanner/daemon — enrichment is best-effort, so a lock
- * degrades to an empty list instead of crashing `agents feed` (RUSH-2006).
- *
- * `load` is injected so tests can throw a real lock-shaped error without
- * mocking the session module.
- */
 export declare function loadSessionMetasForFeedEnrichment<T>(load: () => Promise<T[]>): Promise<{
     metas: T[];
     skippedLock: boolean;
 }>;
 export declare function registerFeedCommand(program: Command): void;
-/** Feed view selector (RUSH-2015): decisions, progress, or both. */
 type FeedFilter = 'needs' | 'updates' | 'all';
-/** Normalize a raw --filter value; unknown/empty falls back to the default. */
 export declare function resolveFeedFilter(raw: string | undefined): FeedFilter;
 export {};

package/dist/commands/feed.js

@@ -3,7 +3,7 @@ import { ensureFeedPublishHook, listAskStats, listBlocks, recordNotified, buildD
 import { ensureActivityLogHook, readRecentActivity, formatActivityLine, formatProgressUpdate, mergeActivityEvents, parseActivityPayload, } from '../lib/feed/activity.js';
 import { projectKeyFromCwd } from '../lib/project-key.js';
 import { postFeedStatus } from '../lib/feed-post.js';
-import { linearIssueUrl } from '../lib/session/linear.js';
+import { linearIssueUrl } from '@phnx-labs/sessions-cli/reader';
 import { parseFeedPostLevel, planFeedBroadcast, runFeedBroadcast, effectiveBroadcastConfig, withDesktopNotify, blockBroadcastContext, blockDeliveryFailure, } from '../lib/feed-broadcast.js';
 import { getSessionById, resolveFullSessionId } from '../lib/session/db.js';
 import { fireTraceSyncInBackground } from '../lib/run-trace-sync.js';
@@ -66,12 +66,10 @@ phone-worthy successful update. Use --blocked only when work cannot continue.
 The owner destination comes from humans.yaml; do not duplicate it in agents.yaml.
 `;
 const FEED_NO_FANOUT_ENV = 'AGENTS_FEED_LOCAL';
-/** Right-hand masthead summary: `N blocks · M agents`. */
 export function formatFeedMastheadRight(blocks) {
     const agents = new Set(blocks.map((b) => b.mailboxId)).size;
     return `${blocks.length} block${blocks.length === 1 ? '' : 's'} · ${agents} agent${agents === 1 ? '' : 's'}`;
 }
-/** Reply hint matching the shared fleet-comms reply line. */
 export function formatFeedReplyHint(mailboxId) {
     return `↳ ag message ${mailboxId} "…"`;
 }
@@ -92,16 +90,12 @@ export function parseRemoteFeed(stdout, machine) {
         const block = item;
         if (!block.blockId || !block.sessionId || !block.mailboxId || !block.questions?.length)
             continue;
-        // A crafted mailboxId (path separators, `.`/`..`) would throw inside
-        // mailboxDir() when policy runs against the block, aborting the whole
-        // dispatch loop — drop it here so a malicious peer can't smuggle one in.
         if (!isValidMailboxId(block.mailboxId))
             continue;
         blocks.push({ ...block, host: machine });
     }
     return blocks;
 }
-/** Merge local and remote rows, keeping the first copy of a host/session block. */
 export function mergeFeedBlocks(...groups) {
     const byIdentity = new Map();
     for (const block of groups.flat()) {
@@ -170,10 +164,6 @@ function renderBlock(b, localHost, indent = '') {
     const consequence = b.consequence && b.consequence !== 'normal' ? chalk.red(`[${b.consequence}]`) : '';
     const cost = b.costOfDelay ? chalk.gray(`cost:${b.costOfDelay}`) : '';
     const rank = b.delayRank ? chalk.gray(`rank:${Math.round(b.delayRank.score)}`) : '';
-    // Shared fleet-comms glyphs: ▲ open ask, ✓ answered (see comms-render GLYPH).
-    // A PENDING claim carries an answer record while the block is still open, so
-    // the delivered glyph is driven by the canonical state, not by `b.answer`
-    // being set — a claimed-but-undelivered ask must keep reading as needs-you.
     const marker = deriveBlockState(b) !== 'open'
         ? chalk.green(GLYPH.delivered)
         : b.kind === 'control'
@@ -233,7 +223,6 @@ function renderBlock(b, localHost, indent = '') {
     }
     console.log();
 }
-/** Specific host app + routine provenance for one feed row. */
 export function formatFeedRuntime(block) {
     const host = {
         ghostty: 'Ghostty',
@@ -248,7 +237,6 @@ export function formatFeedRuntime(block) {
         return host;
     return `${host} · routine${block.routineName ? `:${block.routineName}` : ''}`;
 }
-/** Human summary line for one outcome rollup. */
 export function formatOutcomeHeader(group) {
     const { agents, open, answered, parked } = group.counts;
     const parts = [
@@ -269,12 +257,10 @@ function renderOutcomeGroup(group, localHost) {
         renderBlock(b, localHost, '  ');
     }
 }
-/** Map active sessions into the lightweight hints outcome enrichment needs. */
 export function sessionHintsFromActive(sessions) {
     return sessions.map((s) => ({
         sessionId: s.sessionId,
         agentId: s.agentId,
-        // Same precedence as mailboxIdForActiveSession (agentId ?? sessionId).
         mailboxId: s.agentId ?? s.sessionId,
         ticketId: s.ticket?.id,
         prNumber: s.pr?.number,
@@ -286,11 +272,6 @@ export function sessionHintsFromActive(sessions) {
         routineName: s.routineName,
     }));
 }
-/**
- * True when a SQLite open/query failed because another writer holds the lock.
- * better-sqlite3 surfaces this as message "database is locked" and/or code
- * SQLITE_BUSY (RUSH-2006).
- */
 export function isSqliteBusyError(err) {
     if (err == null)
         return false;
@@ -300,14 +281,6 @@ export function isSqliteBusyError(err) {
         : '';
     return /SQLITE_BUSY|database is locked/i.test(msg) || /SQLITE_BUSY/i.test(code);
 }
-/**
- * Load session metas for feed outcome enrichment. The sessions index can be
- * locked by a concurrent scanner/daemon — enrichment is best-effort, so a lock
- * degrades to an empty list instead of crashing `agents feed` (RUSH-2006).
- *
- * `load` is injected so tests can throw a real lock-shaped error without
- * mocking the session module.
- */
 export async function loadSessionMetasForFeedEnrichment(load) {
     try {
         return { metas: await load(), skippedLock: false };
@@ -319,11 +292,6 @@ export async function loadSessionMetasForFeedEnrichment(load) {
         throw err;
     }
 }
-/**
- * One human line per answer outcome. The three states the operator has to tell
- * apart are a real receipt, a hand-off no rail can confirm, and a refusal —
- * never collapsed into a single "Delivered" (PHNX-3999).
- */
 function renderAnswerResult(result) {
     switch (result.status) {
         case 'failed':
@@ -362,8 +330,6 @@ export function registerFeedCommand(program) {
         .action(async (attentionKey, opts, invoked) => {
         const wantsJson = Boolean(opts.json || invoked.parent?.opts()?.json);
         try {
-            // The key's own host decides the rail; `answerOwnerIsLocal` normalizes
-            // both sides so a `.local` suffix is not read as a different machine.
             const { host: ownerHost } = parseAttentionKey(attentionKey);
             const local = answerOwnerIsLocal(ownerHost);
             if (opts.check && (opts.choice != null || opts.text != null)) {
@@ -388,9 +354,6 @@ export function registerFeedCommand(program) {
                 console.log(renderAnswerResult(result));
         }
         catch (error) {
-            // A failure is a first-class outcome for the operator UI, not a parse
-            // error: `--json` still gets a result object it can branch on, with a
-            // non-zero exit so a scripted caller sees the failure too.
             const message = error instanceof Error ? error.message : String(error);
             if (wantsJson) {
                 const failure = {
@@ -419,9 +382,6 @@ export function registerFeedCommand(program) {
         .option('--json', 'Emit the written event as JSON')
         .addHelpText('after', FEED_POST_HELP)
         .action(async (textParts, opts, cmd) => {
-        // Parent `feed` also declares `--json` (for the list view). Commander
-        // binds the flag on the parent, so a `feed post … --json` lands on
-        // parent.opts().json — not the child. Read both.
         const flags = {
             title: opts?.title ?? cmd?.opts?.()?.title,
             session: opts?.session ?? cmd?.opts?.()?.session,
@@ -434,10 +394,6 @@ export function registerFeedCommand(program) {
             json: Boolean(opts?.json ?? cmd?.opts?.()?.json ?? cmd?.parent?.opts?.()?.json),
         };
         try {
-            // Blocked is a state, not a volume: it always broadcasts at `important`,
-            // so an agent has exactly one thing to say. Passing both is a usage
-            // error rather than a silent override -- an agent that thinks it chose
-            // the level should not be quietly ignored.
             if (flags.blocked && flags.level && flags.level !== 'milestone') {
                 throw new Error('--blocked already broadcasts at important; drop --level.');
             }
@@ -456,10 +412,6 @@ export function registerFeedCommand(program) {
                 attach: flags.attach,
                 blocked: flags.blocked,
             });
-            // A blocked post lands in BOTH stores: the event in the shared activity
-            // stream (what happened) and an OpenBlock in the ledger (what is still
-            // open). The ledger is what makes it answerable and clearable -- without
-            // it the ask would scroll away like any other update.
             let outcomes;
             if (flags.blocked) {
                 const block = buildDeclaredBlock({
@@ -469,7 +421,6 @@ export function registerFeedCommand(program) {
                     runtime: event.runtime,
                     cwd: event.cwd,
                 }, {
-                    // Prefer title as the front-loaded ask on the phone; body is detail.
                     text: event.title
                         ? (event.detail ? `${event.title}: ${event.detail}` : event.title)
                         : (event.detail ?? ''),
@@ -487,13 +438,6 @@ export function registerFeedCommand(program) {
             else {
                 outcomes = await broadcastPostedEvent(event, level, meta, flags.notify);
             }
-            // Fail loud when a block reached nobody. This is computed BEFORE the
-            // --json early return: a machine caller is exactly the one that reads the
-            // exit code, so returning 0 there while a human gets 1 would make the
-            // undelivered block invisible to the caller most likely to act on it —
-            // reintroducing, behind a flag, the silent failure this exists to remove.
-            // One sink failing among several stays a warning: the channels are
-            // redundant by design.
             const undelivered = blockDeliveryFailure(flags.blocked, outcomes);
             if (undelivered)
                 process.exitCode = 1;
@@ -519,9 +463,6 @@ export function registerFeedCommand(program) {
         const includeLocal = shouldIncludeLocalFeed(opts.device, self);
         const setupWarnings = [];
         if (includeLocal) {
-            // Feed and activity hooks are independent -- install both, and register
-            // the manifest as long as at least one wrote its entries (don't couple
-            // activity registration to the feed hook succeeding).
             const hookInstall = ensureFeedPublishHook();
             const activityInstall = ensureActivityLogHook();
             if (hookInstall.error)
@@ -542,8 +483,6 @@ export function registerFeedCommand(program) {
                 }
             }
         }
-        // Trailing lane under the block views: `--filter all` appends the same
-        // fleet-wide updates section, anything else the compact local lane.
         const renderTrailingActivity = async () => {
             if (filter === 'all') {
                 console.log();
@@ -555,10 +494,6 @@ export function registerFeedCommand(program) {
             if (includeLocal)
                 renderActivityLane(opts.project);
         };
-        // Updates view: deliberate progress posts only (blocks are decisions, not
-        // announcements). Short-circuits the block pipeline — no dispatch policy —
-        // but fans out like the block view, because a post lands on whichever box
-        // ran the agent.
         if (filter === 'updates') {
             for (const warning of setupWarnings) {
                 console.error(chalk.yellow(`Feed hook setup warning: ${warning}`));
@@ -577,14 +512,10 @@ export function registerFeedCommand(program) {
             renderUpdatesView(updates, opts.project);
             return;
         }
-        // Active sessions feed both the GC sweep and outcome enrichment (ticket/PR).
         let sessions = [];
         if (includeLocal) {
             sessions = await getActiveSessions();
         }
-        // discoverSessions touches sessions.db; under concurrent scan pressure it
-        // can throw SQLITE_BUSY. Outcome enrichment is best-effort — degrade with
-        // a warning rather than crash the whole feed (RUSH-2006).
         let sessionMetas = [];
         if (includeLocal && sessions.length > 0) {
             const loaded = await loadSessionMetasForFeedEnrichment(() => discoverSessions({ all: true, limit: 5000 }));
@@ -605,8 +536,6 @@ export function registerFeedCommand(program) {
             return;
         }
         if (opts.dispatch && includeLocal) {
-            // Liveness sweep: drop messages to dead agents and retire stale blocks
-            // before we render the feed.
             const activeBoxIds = new Set(sessions.map(mailboxIdForActiveSession).filter((id) => !!id));
             const gcResult = gcMailbox(activeBoxIds);
             if (gcResult.blocksRemoved > 0 || gcResult.messagesDroppedDead > 0) {
@@ -616,15 +545,9 @@ export function registerFeedCommand(program) {
         let localBlocks = includeLocal
             ? [...listBlocks(), ...synthesizeControlCards(localSignals, listAskStats())]
             : [];
-        // Fill missing ticket/PR/worktree from live session meta before local
-        // policy mutates the store, so outcome keys land even when the publish
-        // hook had no deliverable stamp.
         if (sessions.length > 0) {
             localBlocks = enrichBlocksFromSessions(localBlocks, sessionHintsFromActive(sessions));
         }
-        // Stall suppression (RUSH-1477) must only mutate blocks owned by this
-        // machine. Remote peers run their own `feed --json`; never enqueue a
-        // policy answer into a local mailbox for a remote agent.
         const preparedLocal = prepareLocalFeedBlocks(localBlocks, {
             includeLocal,
             all: opts.all,
@@ -638,7 +561,6 @@ export function registerFeedCommand(program) {
             const remoteHosts = remoteFeedHostsToDial(opts.device, self);
             if (!opts.device?.length || (remoteHosts && remoteHosts.length > 0)) {
                 const remote = await gatherRemoteAgentsJson({
-                    // Bare --json stays a block array so older peers and scripts keep working.
                     args: ['feed', '--json'],
                     noFanoutEnv: FEED_NO_FANOUT_ENV,
                     hosts: remoteHosts,
@@ -659,9 +581,6 @@ export function registerFeedCommand(program) {
             const policy = loadPolicy();
             const now = new Date();
             for (const b of dispatchBlocksProject) {
-                // Wrap per-block policy so one malformed block (e.g. a crafted
-                // mailboxId that throws in mailboxDir) can't abort the whole loop and
-                // strand every remaining block's dispatch.
                 try {
                     const result = applyPolicyToBlock(b, policy, now);
                     if (result.action !== 'none') {
@@ -687,8 +606,6 @@ export function registerFeedCommand(program) {
             console.error(chalk.yellow(`Feed hook setup warning: ${warning}`));
         }
         if (opts.json) {
-            // Always a block array (stamped with outcome + ask class) so remote fan-out
-            // and scripts keep a stable contract. Human grouping is text-only.
             const stamped = stampBlockOutcomes(blocks).map((b) => ({
                 ...b,
                 ask: classifyBlock(b),
@@ -701,7 +618,6 @@ export function registerFeedCommand(program) {
             await renderTrailingActivity();
             return;
         }
-        // Shared fleet-comms masthead (same family as `agents mailboxes`).
         console.log(masthead({
             title: opts.project ? `${opts.project} needs you` : 'they need you',
             accent: 'amber',
@@ -724,28 +640,10 @@ export function registerFeedCommand(program) {
         await renderTrailingActivity();
     });
 }
-/**
- * Mirror a written post to the configured sinks (`feed.broadcast` in
- * agents.yaml, or the implicit `notify.owner` fallback for an important post —
- * see {@link effectiveBroadcastConfig}). The ticket is JOINED from the session
- * index rather than asked for as a flag — it is a domain fact about the
- * session, and an agent that has to remember a `--ticket` argument is an agent
- * that will forget it. Returns the per-sink outcomes; an empty array means
- * nothing is configured and no fallback applies, which is not a failure for a
- * routine post (see `blockDeliveryFailure` for the `--blocked` case).
- *
- * `meta` is threaded in rather than read here so the fallback/config decision
- * and the delivery are pinned to one config snapshot, and so this is testable
- * against a real in-memory `Meta` without touching `~/.agents/agents.yaml`.
- */
 async function broadcastPostedEvent(event, level, meta, notify = false) {
-    // `--notify` adds a local desktop banner on top of the configured sinks; it
-    // fires even for a milestone post that no configured sink would broadcast.
     const config = withDesktopNotify(effectiveBroadcastConfig(meta.feed?.broadcast, level, meta), notify);
     if (!config)
         return [];
-    // Upgrade an 8-char footer crumb to the full indexed id so the console session
-    // URL resolves instead of 404ing, and so the ticket join hits the right row.
     const session = resolveFullSessionId(event.sessionId) ?? event.sessionId;
     const ticket = getSessionById(session)?.ticketId;
     const planned = planFeedBroadcast(config, {
@@ -762,22 +660,10 @@ async function broadcastPostedEvent(event, level, meta, notify = false) {
             .map((a) => a.href)
             .filter((href) => /^https?:\/\//i.test(href)),
     }, meta);
-    // An important post links the session's console page; fire the trace sync now
-    // so that page exists when the owner taps it (trace sync otherwise waits for
-    // run exit — PHNX-3628/PHNX-3698). Gated + best-effort, never blocks the post.
     if (level === 'important')
         fireTraceSyncInBackground();
     return runFeedBroadcast(planned, meta);
 }
-/**
- * Mirror a declared block to the same sinks a post reaches (plus the implicit
- * `notify.owner` fallback — a block is always `important`, so it always
- * qualifies).
- *
- * Blocks previously never broadcast at all: `broadcastPostedEvent` ran only for
- * `feed post`, while every `publishBlock` call wrote to the ledger and stopped
- * there — so a "needs you" record was durable and invisible at the same time.
- */
 async function broadcastBlock(block, extras, meta, notify = false) {
     const config = withDesktopNotify(effectiveBroadcastConfig(meta.feed?.broadcast, 'important', meta), notify);
     if (!config)
@@ -785,12 +671,9 @@ async function broadcastBlock(block, extras, meta, notify = false) {
     const sessionId = resolveFullSessionId(block.sessionId) ?? block.sessionId;
     const ticket = getSessionById(sessionId)?.ticketId;
     const ctx = blockBroadcastContext({ ...block, sessionId, ticket: block.ticket ?? ticket }, extras);
-    // A block is always important and links the session's console page — fire the
-    // trace sync so the page exists when tapped (best-effort, gated, non-blocking).
     fireTraceSyncInBackground();
     return runFeedBroadcast(planFeedBroadcast(config, ctx, meta), meta);
 }
-/** One line per sink that ran. Silent when nothing is configured. */
 function reportBroadcast(outcomes) {
     for (const o of outcomes) {
         if (o.ok && o.error)
@@ -801,7 +684,6 @@ function reportBroadcast(outcomes) {
             console.error(chalk.yellow(`  → ${o.name} failed: ${o.error}`));
     }
 }
-/** Normalize a raw --filter value; unknown/empty falls back to the default. */
 export function resolveFeedFilter(raw) {
     const v = (raw ?? '').trim().toLowerCase();
     if (v === 'updates' || v === 'update')
@@ -810,23 +692,16 @@ export function resolveFeedFilter(raw) {
         return 'all';
     return 'needs';
 }
-/** True when a block belongs to the requested project (case-insensitive). */
 function blockMatchesProject(block, project) {
     if (!project)
         return true;
     return (block.project ?? '').toLowerCase() === project.toLowerCase();
 }
-/** True when an activity event belongs to the requested project (case-insensitive). */
 function eventMatchesProject(ev, project) {
     if (!project)
         return true;
     return ((ev.project ?? projectKeyFromCwd(ev.cwd) ?? '')).toLowerCase() === project.toLowerCase();
 }
-/**
- * Render one activity event in the lane: deliberate progress posts
- * (`status.posted`) use the rich multi-line {@link formatProgressUpdate}; hook
- * milestones (PR, commit, …) keep the compact {@link formatActivityLine}.
- */
 function renderActivityEntry(ev) {
     if (ev.event === 'status.posted') {
         console.log(formatProgressUpdate(ev));
@@ -835,17 +710,9 @@ function renderActivityEntry(ev) {
         console.log(formatActivityLine(ev, { showHost: true }));
     }
 }
-/** How far back the updates view looks for deliberate progress posts. */
 const UPDATES_WINDOW_MS = 7 * 24 * 60 * 60 * 1000;
-/** Posts kept per machine in the rendered view / the `--json` payload. */
 const UPDATES_VIEW_LIMIT = 30;
 const UPDATES_JSON_LIMIT = 100;
-/**
- * The most recent `limit` deliberate progress posts on THIS machine, newest
- * first. The event filter is pushed into the reader so `limit` counts posts —
- * slicing first and filtering after returned an empty view on a busy box, where
- * routine `file.edited` hook events fill the whole slice.
- */
 function readStatusPosts(limit) {
     return readRecentActivity({
         sinceMs: Date.now() - UPDATES_WINDOW_MS,
@@ -853,12 +720,6 @@ function readStatusPosts(limit) {
         events: ['status.posted'],
     });
 }
-/**
- * Progress posts across the fleet, newest first. An agent posts on whichever
- * box it runs on, so a local-only read shows the operator a fraction of what
- * the fleet reported. Peers are dialed with the same SSH fan-out the block view
- * uses; `--local` (or the no-fanout env guard on a peer) keeps it to this box.
- */
 async function gatherStatusPosts(opts) {
     const local = opts.includeLocal
         ? readStatusPosts(opts.limit).filter((ev) => eventMatchesProject(ev, opts.project))
@@ -878,11 +739,6 @@ async function gatherStatusPosts(opts) {
     const merged = mergeActivityEvents(local, remote.items).filter((ev) => eventMatchesProject(ev, opts.project));
     return merged.slice(0, opts.limit);
 }
-/**
- * Render the **Updates** view: deliberate progress posts only (`status.posted`),
- * recency-ordered, with rich identity chips. Pure `file.edited` / git-hook noise
- * is excluded so operators see announcements, not tool churn.
- */
 function renderUpdatesView(updates, project) {
     const hosts = new Set(updates.map((e) => e.host).filter(Boolean));
     console.log(masthead({
@@ -901,12 +757,6 @@ function renderUpdatesView(updates, project) {
         console.log();
     }
 }
-/**
- * Print a compact "recent activity" lane under the feed: the last few milestone
- * events (plans, PRs, worktrees, sub-agents, progress posts) from the append-only
- * activity logs. Read-only tail of the logs -- no transcript re-parsing. Silent
- * when empty.
- */
 function renderActivityLane(project, limit = 6) {
     const events = readRecentActivity({
         sinceMs: Date.now() - 24 * 60 * 60 * 1000,

package/dist/commands/feedback.d.ts

@@ -1,7 +1,2 @@
-/**
- * `agents feedback` — frictionless, in-CLI feedback. Opens a Discussion
- * pre-filled with version + OS + agent inventory; falls back to printing the
- * URL when no browser is available.
- */
 import type { Command } from 'commander';
 export declare function registerFeedbackCommand(program: Command): void;

package/dist/commands/feedback.js

@@ -1,8 +1,3 @@
-/**
- * `agents feedback` — frictionless, in-CLI feedback. Opens a Discussion
- * pre-filled with version + OS + agent inventory; falls back to printing the
- * URL when no browser is available.
- */
 import { arch, platform, release } from 'node:os';
 import { createRequire } from 'node:module';
 import chalk from 'chalk';

package/dist/commands/fleet-capture.d.ts

@@ -1,14 +1,2 @@
-/**
- * `agents fleet capture` (alias surface of `agents devices capture`) — snapshot
- * the live environment into the `fleet:` block of `agents.yaml` so a fresh
- * machine can reconstruct it with `agents fleet apply`.
- *
- * Local-read + local-write, zero SSH. Records device NAMES only (never IPs or
- * usernames — those are re-resolved live from Tailscale at apply-time), plus the
- * source's own agents as defaults, browser profiles, secrets-bundle names, and
- * routine names. The heavy lifting is the pure `captureFleet` builder; this
- * command just gathers inputs and persists via `updateMeta`.
- */
 import { Command } from 'commander';
-/** Attach `capture` to the `devices`/`fleet` command tree. */
 export declare function registerFleetCaptureCommand(devicesCmd: Command): void;