@phnx-labs/agents-cli 1.22.114 → 1.22.116

package/dist/lib/session/prompt.d.ts

@@ -96,15 +96,31 @@ export declare function classifyUserPrompt(raw: string | undefined, opts?: {
     hasImageAttachment?: boolean;
 }): ClassifiedPrompt;
 /**
- * Collapse a harness-generated session title when it is injected skill
- * scaffolding; otherwise leave the title as the harness wrote it.
+ * Reduce a harness-generated session title to something worth showing as a
+ * headline, or `undefined` when it is not (PHNX-3999 F26/F27).
  *
  * Claude's `ai-title` and Cursor's `chatMeta.title` are both derived from the
- * first turn, so a session opened with a skill gets named after the injected
- * "Base directory for this skill: …" line. {@link classifyUserPrompt} reports
- * `kind: 'skill'` only for that line, so collapse it to `/<skill>`. Empty or
- * whitespace-only input yields `undefined` so the caller falls through to the
- * first-prompt topic.
+ * FIRST turn of the transcript, so whatever the harness injected there becomes
+ * the session's name: a skill's install-directory preamble, a `!`-prefixed shell
+ * echo wrapped in `<bash-input>`, a `/clear`. The owner's recording shows both
+ * failures — one row titled with shell-command XML wrappers, others reading
+ * `/clear`. Three rungs, in order:
+ *
+ *  1. A skill invocation collapses to `/<skill>` ({@link classifyUserPrompt}
+ *     reports `kind: 'skill'` only for that injected line).
+ *  2. Harness scaffolding is REJECTED, not cleaned: `<bash-input>`,
+ *     `<command-name>`, `<local-command-stdout>`, `<system-reminder>` and the
+ *     rest of {@link isSyntheticUserMessage}'s cross-harness list, plus a title
+ *     that is only tags. Stripping the tags would leave the shell command
+ *     itself as the headline, which is the same wrong answer with tidier
+ *     punctuation.
+ *  3. A bare control command is rejected ({@link BARE_CONTROL_COMMAND_RE}).
+ *
+ * A rejected label returns `undefined`, so the row falls to the next rung of the
+ * canonical ladder — the daemon-generated title, then the user's own first
+ * prompt (`sessionHeadline`, `session/title.ts`). Nothing is deleted: the
+ * original turn stays on the row as `firstUserMessage` / `request`, so the
+ * details view still shows exactly what the agent was told.
  *
  * A user-authored title (Claude `/rename` / `custom-title`) is never passed
  * here — the caller keeps it verbatim.

package/dist/lib/session/prompt.js

@@ -295,15 +295,45 @@ export function classifyUserPrompt(raw, opts = {}) {
     return { clean: display, kind: 'text' };
 }
 /**
- * Collapse a harness-generated session title when it is injected skill
- * scaffolding; otherwise leave the title as the harness wrote it.
+ * A label that is nothing but a control command — `/clear`, `/compact`,
+ * `/model`, `/exit` — with no words of its own after it.
+ *
+ * One rule instead of a per-harness list of control verbs: a title that is a
+ * bare slash token describes an action taken ON the session, never what the
+ * session is about, so whatever it names it is not a headline. A command WITH an
+ * argument (`/continue fix the parser`, `/code:commit the retry fix`) carries
+ * real intent and is kept.
+ *
+ * Skill collapse runs first in {@link cleanGeneratedSessionLabel} and returns
+ * its own `/<skill>` form, so this never swallows that deliberate shape.
+ */
+const BARE_CONTROL_COMMAND_RE = /^\/[\w:-]+$/;
+/**
+ * Reduce a harness-generated session title to something worth showing as a
+ * headline, or `undefined` when it is not (PHNX-3999 F26/F27).
  *
  * Claude's `ai-title` and Cursor's `chatMeta.title` are both derived from the
- * first turn, so a session opened with a skill gets named after the injected
- * "Base directory for this skill: …" line. {@link classifyUserPrompt} reports
- * `kind: 'skill'` only for that line, so collapse it to `/<skill>`. Empty or
- * whitespace-only input yields `undefined` so the caller falls through to the
- * first-prompt topic.
+ * FIRST turn of the transcript, so whatever the harness injected there becomes
+ * the session's name: a skill's install-directory preamble, a `!`-prefixed shell
+ * echo wrapped in `<bash-input>`, a `/clear`. The owner's recording shows both
+ * failures — one row titled with shell-command XML wrappers, others reading
+ * `/clear`. Three rungs, in order:
+ *
+ *  1. A skill invocation collapses to `/<skill>` ({@link classifyUserPrompt}
+ *     reports `kind: 'skill'` only for that injected line).
+ *  2. Harness scaffolding is REJECTED, not cleaned: `<bash-input>`,
+ *     `<command-name>`, `<local-command-stdout>`, `<system-reminder>` and the
+ *     rest of {@link isSyntheticUserMessage}'s cross-harness list, plus a title
+ *     that is only tags. Stripping the tags would leave the shell command
+ *     itself as the headline, which is the same wrong answer with tidier
+ *     punctuation.
+ *  3. A bare control command is rejected ({@link BARE_CONTROL_COMMAND_RE}).
+ *
+ * A rejected label returns `undefined`, so the row falls to the next rung of the
+ * canonical ladder — the daemon-generated title, then the user's own first
+ * prompt (`sessionHeadline`, `session/title.ts`). Nothing is deleted: the
+ * original turn stays on the row as `firstUserMessage` / `request`, so the
+ * details view still shows exactly what the agent was told.
  *
  * A user-authored title (Claude `/rename` / `custom-title`) is never passed
  * here — the caller keeps it verbatim.
@@ -313,7 +343,15 @@ export function cleanGeneratedSessionLabel(title) {
     if (!trimmed)
         return undefined;
     const classified = classifyUserPrompt(trimmed);
-    return classified.kind === 'skill' ? classified.clean : trimmed;
+    if (classified.kind === 'skill')
+        return classified.clean;
+    if (isSyntheticUserMessage(trimmed))
+        return undefined;
+    if (!stripXmlLikeTags(trimmed).trim())
+        return undefined;
+    if (BARE_CONTROL_COMMAND_RE.test(trimmed))
+        return undefined;
+    return trimmed;
 }
 /**
  * Extract a one-line topic from a raw user message, or undefined if the message

package/dist/lib/session/remote/peer-stream.d.ts

@@ -5,11 +5,29 @@ export declare const PEER_BACKOFF_BASE_MS = 2000;
 export declare const PEER_BACKOFF_CAP_MS = 60000;
 /** Consecutive failed spawns before the peer is parked. */
 export declare const PEER_PARK_AFTER_FAILURES = 3;
+/**
+ * Consecutive failed spawns before the peer is RETIRED — the capped 60 s ladder
+ * gives way to {@link PEER_RETIRED_RECHECK_MS}.
+ *
+ * The cap alone bounds the delay but not the total work: a box that is off for a
+ * weekend was dialed every 60 s for two days, ~2,880 ssh children per watcher
+ * per peer, each one already known to fail. Ten consecutive failures is well
+ * past any transient network event, so past that point the peer is treated as
+ * genuinely absent and re-dialed on the slow cadence instead.
+ */
+export declare const PEER_RETIRE_AFTER_FAILURES = 10;
+/**
+ * Re-dial cadence for a retired peer. Still bounded rather than never, because a
+ * box can come back without anything touching the device registry — waiting
+ * only on a registry change would leave it unreachable until an operator acted.
+ */
+export declare const PEER_RETIRED_RECHECK_MS: number;
 /**
  * Reconnect delay for `failures` consecutive failed spawns: 0 for a healthy
- * peer, then {@link PEER_BACKOFF_BASE_MS} doubling to {@link PEER_BACKOFF_CAP_MS}.
+ * peer, then {@link PEER_BACKOFF_BASE_MS} doubling to {@link PEER_BACKOFF_CAP_MS},
+ * and {@link PEER_RETIRED_RECHECK_MS} once the peer is retired.
  */
-export declare function peerBackoffDelayMs(failures: number, base?: number, cap?: number): number;
+export declare function peerBackoffDelayMs(failures: number, base?: number, cap?: number, retireAfter?: number, retiredMs?: number): number;
 interface PeerStreamOptions {
     /** The device to subscribe to. */
     device: DeviceProfile;
@@ -29,6 +47,10 @@ interface PeerStreamOptions {
     backoffCapMs?: number;
     /** Override the park threshold (tests). */
     parkAfterFailures?: number;
+    /** Override the retire threshold (tests). */
+    retireAfterFailures?: number;
+    /** Override the retired re-dial cadence (tests). */
+    retiredRecheckMs?: number;
     /** Override the ssh binary (tests). */
     sshBin?: string;
     /** Override the parked peer's registry re-check cadence (tests). */

package/dist/lib/session/remote/peer-stream.js

@@ -19,6 +19,9 @@
  * - a peer that fails {@link PEER_PARK_AFTER_FAILURES} spawns in a row parked —
  *   it stops the reconnect cycle and re-dials only when the device registry
  *   changes or the capped backoff elapses;
+ * - a peer that fails {@link PEER_RETIRE_AFTER_FAILURES} in a row RETIRED — the
+ *   capped 60 s ladder is itself unbounded in total work, so past that point the
+ *   re-dial drops to {@link PEER_RETIRED_RECHECK_MS};
  * - abort listeners removed per iteration, so a watcher open for hours does not
  *   accumulate one per reconnect on the caller's AbortSignal.
  */
@@ -34,17 +37,37 @@ export const PEER_BACKOFF_BASE_MS = 2_000;
 export const PEER_BACKOFF_CAP_MS = 60_000;
 /** Consecutive failed spawns before the peer is parked. */
 export const PEER_PARK_AFTER_FAILURES = 3;
+/**
+ * Consecutive failed spawns before the peer is RETIRED — the capped 60 s ladder
+ * gives way to {@link PEER_RETIRED_RECHECK_MS}.
+ *
+ * The cap alone bounds the delay but not the total work: a box that is off for a
+ * weekend was dialed every 60 s for two days, ~2,880 ssh children per watcher
+ * per peer, each one already known to fail. Ten consecutive failures is well
+ * past any transient network event, so past that point the peer is treated as
+ * genuinely absent and re-dialed on the slow cadence instead.
+ */
+export const PEER_RETIRE_AFTER_FAILURES = 10;
+/**
+ * Re-dial cadence for a retired peer. Still bounded rather than never, because a
+ * box can come back without anything touching the device registry — waiting
+ * only on a registry change would leave it unreachable until an operator acted.
+ */
+export const PEER_RETIRED_RECHECK_MS = 15 * 60_000;
 /** Bytes of a peer's stderr retained for the `unavailable` reason. */
 const PEER_STDERR_BYTES = 2_048;
 /** How often a parked peer re-checks the device registry for a refresh. */
 const PEER_REGISTRY_POLL_MS = 5_000;
 /**
  * Reconnect delay for `failures` consecutive failed spawns: 0 for a healthy
- * peer, then {@link PEER_BACKOFF_BASE_MS} doubling to {@link PEER_BACKOFF_CAP_MS}.
+ * peer, then {@link PEER_BACKOFF_BASE_MS} doubling to {@link PEER_BACKOFF_CAP_MS},
+ * and {@link PEER_RETIRED_RECHECK_MS} once the peer is retired.
  */
-export function peerBackoffDelayMs(failures, base = PEER_BACKOFF_BASE_MS, cap = PEER_BACKOFF_CAP_MS) {
+export function peerBackoffDelayMs(failures, base = PEER_BACKOFF_BASE_MS, cap = PEER_BACKOFF_CAP_MS, retireAfter = PEER_RETIRE_AFTER_FAILURES, retiredMs = PEER_RETIRED_RECHECK_MS) {
     if (failures <= 0)
         return 0;
+    if (failures >= retireAfter)
+        return retiredMs;
     return Math.min(cap, base * 2 ** (failures - 1));
 }
 /** Bounded tail of a child's stderr, kept for the unavailable reason. */
@@ -133,10 +156,14 @@ export async function streamFromPeer(options) {
         failures += 1;
         const exit = code == null ? 'ssh failed' : `ssh exited ${code}`;
         const parked = failures >= parkAfter;
-        const delay = peerBackoffDelayMs(failures, options.backoffBaseMs, options.backoffCapMs);
-        options.onUnavailable(parked
-            ? `${reasonFor(exit, stderr)} — parked after ${failures} failed connections, retrying in ${Math.round(delay / 1000)}s or on a device refresh`
-            : reasonFor(exit, stderr));
+        const retireAfter = options.retireAfterFailures ?? PEER_RETIRE_AFTER_FAILURES;
+        const retired = failures >= retireAfter;
+        const delay = peerBackoffDelayMs(failures, options.backoffBaseMs, options.backoffCapMs, retireAfter, options.retiredRecheckMs);
+        options.onUnavailable(retired
+            ? `${reasonFor(exit, stderr)} — retired after ${failures} failed connections, re-dialing in ${Math.round(delay / 60_000)}min or on a device refresh`
+            : parked
+                ? `${reasonFor(exit, stderr)} — parked after ${failures} failed connections, retrying in ${Math.round(delay / 1000)}s or on a device refresh`
+                : reasonFor(exit, stderr));
         await parkedWait(options, delay);
     }
 }

package/dist/lib/session/remote/remote-list.d.ts

@@ -124,6 +124,26 @@ export declare function resolvePeerTarget(machine: string): Promise<{
  * error, timeout, version-skewed peer with no `--json` preview envelope.
  */
 export declare function fetchPeerPreviewDigest(sessionId: string, machine: string, timeoutMs?: number): Promise<unknown | undefined>;
+export type PeerPreviewEnvelopeResult = {
+    ok: true;
+    envelope: unknown;
+} | {
+    ok: false;
+    reason: 'no-target' | 'unreachable' | 'invalid-json';
+};
+/**
+ * Fetch the FULL `agents sessions preview <id> --local --json` envelope
+ * (session/active/preview/error, not just the `.preview` slice
+ * {@link fetchPeerPreviewDigest} narrows to) from a session's owning peer in
+ * exactly ONE bounded {@link sshCapture} hop. This is the canonical exact
+ * ID+owner preview loader (PHNX-3999): the peer's own command already runs the
+ * owner-side bounded parsers/fold (`loadSessionPreviewDigest`) and existing
+ * redaction, so a caller that already knows the owning device needs no
+ * separate metadata round trip before this one — unlike the general fleet
+ * resolver, which fans out a `sessions <id> --json --all` metadata query first
+ * because it does NOT yet know which peer (if any) holds the id.
+ */
+export declare function fetchPeerPreviewEnvelope(sessionId: string, machine: string, timeoutMs?: number): Promise<PeerPreviewEnvelopeResult>;
 /** Parse the JSON envelope returned by `sessions preview --json`. */
 export declare function parsePeerPreviewDigest(parsed: unknown): unknown | undefined;
 /**

package/dist/lib/session/remote/remote-list.js

@@ -540,21 +540,37 @@ const PEER_PREVIEW_TIMEOUT_MS = 15_000;
  * error, timeout, version-skewed peer with no `--json` preview envelope.
  */
 export async function fetchPeerPreviewDigest(sessionId, machine, timeoutMs = PEER_PREVIEW_TIMEOUT_MS) {
+    const envelope = await fetchPeerPreviewEnvelope(sessionId, machine, timeoutMs);
+    if (!envelope.ok)
+        return undefined;
+    return parsePeerPreviewDigest(envelope.envelope);
+}
+/**
+ * Fetch the FULL `agents sessions preview <id> --local --json` envelope
+ * (session/active/preview/error, not just the `.preview` slice
+ * {@link fetchPeerPreviewDigest} narrows to) from a session's owning peer in
+ * exactly ONE bounded {@link sshCapture} hop. This is the canonical exact
+ * ID+owner preview loader (PHNX-3999): the peer's own command already runs the
+ * owner-side bounded parsers/fold (`loadSessionPreviewDigest`) and existing
+ * redaction, so a caller that already knows the owning device needs no
+ * separate metadata round trip before this one — unlike the general fleet
+ * resolver, which fans out a `sessions <id> --json --all` metadata query first
+ * because it does NOT yet know which peer (if any) holds the id.
+ */
+export async function fetchPeerPreviewEnvelope(sessionId, machine, timeoutMs = PEER_PREVIEW_TIMEOUT_MS) {
     const peer = await resolvePeerTarget(machine);
     if (!peer)
-        return undefined;
+        return { ok: false, reason: 'no-target' };
     const cmd = remoteListCommand(['sessions', 'preview', sessionId, '--local', '--json'], peer.os);
     const capture = await sshCapture(peer.target, cmd, timeoutMs);
     if (capture.code !== 0)
-        return undefined;
-    let parsed;
+        return { ok: false, reason: 'unreachable' };
     try {
-        parsed = JSON.parse(stripClixml(capture.stdout));
+        return { ok: true, envelope: JSON.parse(stripClixml(capture.stdout)) };
     }
     catch {
-        return undefined;
+        return { ok: false, reason: 'invalid-json' };
     }
-    return parsePeerPreviewDigest(parsed);
 }
 /** Parse the JSON envelope returned by `sessions preview --json`. */
 export function parsePeerPreviewDigest(parsed) {

package/dist/lib/session/remote/watch.d.ts

@@ -59,6 +59,18 @@ export interface SessionWatchRow extends Omit<ActiveSession, 'viewingIn' | 'cont
     branch?: string;
     rowKey: string;
     sourceDevice: string;
+    /**
+     * The registered project this session's working directory belongs to, or
+     * `null` when the association is not confirmed (PHNX-3999 F08/F09).
+     *
+     * This is what a UI groups by. It is deliberately not `project`: that field is
+     * a bucket KEY derived from the path (the basename of the cwd, so it always
+     * answers something), which is how a loose or unrelated directory became its
+     * own project group. `null` means Uncategorized — the row is still listed, it
+     * just is not filed under a project nobody bound it to. Resolved on the device
+     * that owns the path, since a definition's root is a local path.
+     */
+    confirmedProject: string | null;
     /** Durable index rows are kept on the stream under a distinct identity so a
      * live row can replace/disappear without erasing its recoverable history. */
     previous: boolean;

package/dist/lib/session/remote/watch.js

@@ -1,4 +1,5 @@
 import { SessionProjection } from '../projection.js';
+import { confirmedProjectForCwd } from '../../projects.js';
 import { createHash, randomUUID } from 'node:crypto';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
@@ -40,6 +41,11 @@ export function toSessionWatchRow(scope, row) {
         // no computed summary reads `pending` when the summarizer is on, `skipped`
         // when it is off (PHNX-3939). goal/checkpoints/summaryChecklist rode `...row`.
         summaryState: resolveStreamSummaryState(row.summaryState),
+        // The CONFIRMED project this work belongs to, or null for Uncategorized
+        // (PHNX-3999 F08/F09). Only a registered project definition counts — a
+        // consumer must never group by a directory basename, which is how unrelated
+        // and unbound directories became their own "projects".
+        confirmedProject: confirmedProjectForCwd(row.cwd) ?? null,
         rowKey,
         sourceDevice: scope,
         previous,
@@ -104,7 +110,10 @@ export function toPreviousSessionWatchRow(scope, session) {
         ...(session.harness ? { harness: session.harness } : {}),
         sessionId: session.id,
         ...(session.cwd ? { cwd: session.cwd } : {}),
+        // `project` stays the historical bucket KEY rows are joined on; the grouping a
+        // person sees comes from the confirmed association (PHNX-3999 F08/F09).
         ...(session.project ? { project: session.project } : {}),
+        confirmedProject: confirmedProjectForCwd(session.cwd) ?? null,
         // Same headline ladder as a live row (`deriveSessionRecap`, PHNX-3797):
         // `/rename` label → the daemon-generated title → `request.headline` (the
         // user's own sentence with attachment noise pulled out, PHNX-3939) →

package/dist/lib/session/remote-preview-cache.d.ts

@@ -0,0 +1,29 @@
+/** Bounded, single-owner preview fetch with a durable requester cache and cross-process coalescing. */
+import { fetchPeerPreviewEnvelope } from './remote/remote-list.js';
+export type RemotePreviewCacheState = 'fresh' | 'stale-offline' | 'stale-error' | 'no-cache-offline' | 'no-cache-error' | 'invalid-id';
+export interface RemotePreviewOutcome {
+    envelope?: unknown;
+    cache: {
+        source: 'live' | 'cache';
+        fetchedAt: number | null;
+        stale: boolean;
+        state: RemotePreviewCacheState;
+        device: string;
+        reason: string | null;
+    };
+}
+/** A changed caller cursor invalidates a good copy; failed attempts preserve both its content and cursor. */
+export interface RemotePreviewDeps {
+    /** Defaults to the real bounded SSH transport ({@link fetchPeerPreviewEnvelope}).
+     * Overridable so the cache/backoff/revision/lease STATE MACHINE can be tested
+     * against a real SQLite DB without a live peer — this repo has no fleet in
+     * CI, and the actual bounded-transport behavior (timeout, byte cap) is
+     * already covered where `fetchPeerPreviewEnvelope`/`sshCapture` are defined. */
+    fetchEnvelope: typeof fetchPeerPreviewEnvelope;
+}
+export declare function getRemoteSessionPreview(sessionId: string, device: string, opts?: {
+    refresh?: boolean;
+    revision?: string;
+    now?: number;
+    timeoutMs?: number;
+}, deps?: RemotePreviewDeps): Promise<RemotePreviewOutcome>;