@phnx-labs/agents-cli 1.22.59 → 1.22.61

package/dist/lib/teams/agents.d.ts

@@ -101,6 +101,18 @@ export { captureProcessStartTime };
  * model_reasoning_effort override). Mode (plan/edit/full) is a separate knob.
  */
 export type EffortLevel = 'low' | 'medium' | 'high' | 'xhigh' | 'max' | 'auto';
+/**
+ * Append {@link TEAMMATE_PR_POLICY} to a teammate prompt for every WRITE-capable
+ * mode (all but plan, which is read-only and opens no PR). Exported so the CLOUD
+ * dispatch path (`cloudDispatchOptions` in `commands/teams.ts`) applies the SAME
+ * boundary this file's `buildRunArgv` applies to LOCAL and REMOTE teammates. A
+ * cloud teammate is the case that needs it MOST: it runs in the provider's
+ * sandbox, not the shared local version home, so it never inherits the
+ * `merge-guard.sh` PreToolUse hook — the prompt policy is then its ONLY
+ * self-merge layer. Routing every dispatch surface through one helper keeps that
+ * parity from drifting (PHNX-3236).
+ */
+export declare function withTeammatePrPolicy(prompt: string, mode: string): string;
 export declare const VALID_MODES: readonly ["plan", "edit", "auto", "skip", "full"];
 type Mode = 'plan' | 'edit' | 'auto' | 'skip';
 /** Resolve a mode string to a validated Mode, falling back to the given default. */

package/dist/lib/teams/agents.js

@@ -255,6 +255,49 @@ When you're done, provide a brief summary of:
 const CLAUDE_PLAN_MODE_PREFIX = `You are running in HEADLESS PLAN MODE. This mode works like normal plan mode with one exception: you cannot write to ~/.claude/plans/ directory. Instead of writing a plan file, output your complete plan/response as your final message.
 
 `;
+// PHNX-3236: the teammate self-merge boundary, injected as a DISPATCH DEFAULT.
+// A write-capable teammate has `gh pr merge` and authenticates as the repo owner,
+// so it can merge its OWN PR past the required non-author-review gate — which is
+// exactly what happened in the RUSH-2988 wave-1 dispatch (PR #1817, #1820). The
+// root cause was that the boundary lived in per-brief wording: one teammate in the
+// batch was told "open the PR, don't merge" and held off; the others weren't and
+// self-merged. Making it a default the runner appends to every non-plan teammate
+// gives one HARNESS-INDEPENDENT layer instead of relying on each dispatch prompt
+// remembering to say it. The HARD enforcement is merge-guard.sh — a PreToolUse hook
+// the teammate inherits from the shared version home, whose self-authored-verdict
+// exclusion was closed in the same ticket (.agents-system #395) so a verdict a
+// teammate posts on its own PR no longer clears the gate. The two layers do NOT
+// overlap everywhere: hook-capable local/remote teammates get both, but cloud
+// teammates (provider sandbox, no inherited hook) and hook-incapable harnesses
+// (Warp/oz — no hook surface, no allowlist) get ONLY this prompt, so for them it is
+// a soft control. That residual is documented in cli/AGENTS.md §6; server-side
+// branch protection is the client-independent way to close it. This is the
+// harness-independent layer plus the operator hand-off contract, not a replacement
+// for the hard block where the hard block can run.
+const TEAMMATE_PR_POLICY = `
+
+Teammate PR policy (agents teams): when your work opens a pull request, open it and
+hand it off — do NOT merge your OWN PR unless a NON-AUTHOR review verdict has been
+posted on that same PR. You authenticate as the repo owner and share that one
+GitHub identity with every other teammate, so an APPROVE you post on your own PR
+does not count as a non-author review. \`gh pr merge\` on your own PR is blocked by
+merge-guard until a genuine non-author verdict exists on it; never pass --admin or
+otherwise route around that guard. Report the PR as open and let the orchestrator
+or a separate reviewer take it to merge.`;
+/**
+ * Append {@link TEAMMATE_PR_POLICY} to a teammate prompt for every WRITE-capable
+ * mode (all but plan, which is read-only and opens no PR). Exported so the CLOUD
+ * dispatch path (`cloudDispatchOptions` in `commands/teams.ts`) applies the SAME
+ * boundary this file's `buildRunArgv` applies to LOCAL and REMOTE teammates. A
+ * cloud teammate is the case that needs it MOST: it runs in the provider's
+ * sandbox, not the shared local version home, so it never inherits the
+ * `merge-guard.sh` PreToolUse hook — the prompt policy is then its ONLY
+ * self-merge layer. Routing every dispatch surface through one helper keeps that
+ * parity from drifting (PHNX-3236).
+ */
+export function withTeammatePrPolicy(prompt, mode) {
+    return mode === 'plan' ? prompt : prompt + TEAMMATE_PR_POLICY;
+}
 // Canonical modes plus the historical `full` alias (rewritten to `skip` by
 // normalizeModeValue). Keep `full` listed so user-typed CLI flags and stored
 // metadata that pre-date the rename continue to parse.
@@ -2530,6 +2573,14 @@ export class AgentManager {
                 fullPrompt = CLAUDE_PLAN_MODE_PREFIX + fullPrompt;
             }
         }
+        // PHNX-3236: append the self-merge boundary to every WRITE-capable teammate,
+        // fresh or resumed. A plan-mode teammate produces no PR (read-only), so it is
+        // skipped to keep its prompt clean; every other mode can open — and could
+        // self-merge — a PR, so the policy rides along regardless of harness. The
+        // hard block is still merge-guard.sh (inherited hook); see TEAMMATE_PR_POLICY.
+        // The cloud dispatch path applies the SAME helper (withTeammatePrPolicy) so
+        // local, remote, and cloud teammates never diverge on this boundary.
+        fullPrompt = withTeammatePrPolicy(fullPrompt, mode);
         // Profile target takes precedence — `agents run <profile>` resolves the
         // host harness, version pin, and env injection in one place. Plain
         // version pins only apply when no profile is selected.

package/dist/lib/teams/api.d.ts

@@ -62,6 +62,8 @@ export interface AgentStatusDetail {
     task_type?: TaskType | null;
     /** Device name the teammate runs on for a distributed (--on) teammate; null for local. */
     host?: string | null;
+    /** Absolute path to the teammate's worktree, when known. */
+    workspace_dir?: string | null;
     /** Sanitized evidence observed at the lifecycle boundary that failed. */
     failure?: TeammateFailure | null;
 }
@@ -73,6 +75,7 @@ export interface TaskStatusResult {
         pending: number;
         running: number;
         completed: number;
+        stranded: number;
         failed: number;
         stopped: number;
     };
@@ -126,6 +129,8 @@ export interface AgentStatusSummary {
     /** Device name for a distributed (--on) teammate; null for local. */
     host: string | null;
     failure: TeammateFailure | null;
+    /** Absolute path to the teammate's worktree, when known. */
+    workspace_dir?: string | null;
     /** ISO timestamp — feed back via --since for delta polling. */
     cursor: string;
 }
@@ -137,6 +142,7 @@ export interface TaskStatusSummaryResult {
         pending: number;
         running: number;
         completed: number;
+        stranded: number;
         failed: number;
         stopped: number;
     };
@@ -164,6 +170,8 @@ export interface TaskInfo {
     pending: number;
     running: number;
     completed: number;
+    /** Completed teammates with uncommitted work and no PR (PHNX-2951). */
+    stranded: number;
     failed: number;
     stopped: number;
     workspace_dir: string | null;

package/dist/lib/teams/api.js

@@ -3,6 +3,7 @@ import { getDelta } from './summarizer.js';
 import { debug } from './debug.js';
 import { buildClaudeLabelMap } from '../session/discover.js';
 import { resolveTeammateDelivery } from './delivery.js';
+import { hasUncommittedChanges } from './worktree.js';
 /**
  * Truncate a bash command for status output.
  * Handles heredocs specially - shows the redirect target instead of contents.
@@ -126,6 +127,7 @@ export function toAgentStatusSummary(detail) {
             .map((m) => trimMessage(m)),
         host: detail.host ?? null,
         failure: detail.failure ?? null,
+        workspace_dir: detail.workspace_dir ?? null,
         cursor: detail.cursor,
     };
 }
@@ -207,7 +209,7 @@ parentSessionId) {
         ? allAgents
         : allAgents.filter((a) => a.status === effectiveFilter);
     const agentStatuses = [];
-    const counts = { pending: 0, running: 0, completed: 0, failed: 0, stopped: 0 };
+    const counts = { pending: 0, running: 0, completed: 0, stranded: 0, failed: 0, stopped: 0 };
     // Count ALL agents for summary (not just filtered)
     for (const agent of allAgents) {
         if (agent.status === AgentStatus.PENDING)
@@ -221,6 +223,30 @@ parentSessionId) {
         else if (agent.status === AgentStatus.STOPPED)
             counts.stopped++;
     }
+    // Stranded count is computed over ALL agents, not the filter-narrowed view,
+    // so a `--filter running` status still reports teammates that completed dirty.
+    // Cache the probe result so we can reuse it when building details for the
+    // filtered subset without probing the worktree twice.
+    const uncommittedCache = new Map();
+    for (const agent of allAgents) {
+        if (agent.status !== AgentStatus.COMPLETED)
+            continue;
+        const shouldProbeWorktree = !agent.prUrl?.trim() &&
+            !agent.hostName &&
+            Boolean(agent.workspaceDir);
+        const hasUncommitted = shouldProbeWorktree
+            ? await hasUncommittedChanges(agent.workspaceDir)
+            : false;
+        uncommittedCache.set(agent.agentId, hasUncommitted);
+        const delivery = resolveTeammateDelivery({
+            status: agent.status,
+            prUrl: agent.prUrl,
+            hasUncommittedChanges: hasUncommitted,
+        });
+        if (delivery === 'stranded') {
+            counts.stranded++;
+        }
+    }
     // Build details only for filtered agents
     let maxTimestamp = since || new Date(0).toISOString(); // Track max timestamp for cursor
     const claudeLabels = allAgents.some((agent) => agent.agentType === 'claude')
@@ -237,6 +263,12 @@ parentSessionId) {
         if (agentTimestamp > maxTimestamp) {
             maxTimestamp = agentTimestamp;
         }
+        const hasUncommitted = uncommittedCache.get(agent.agentId) ?? false;
+        const delivery = resolveTeammateDelivery({
+            status: agent.status,
+            prUrl: agent.prUrl,
+            hasUncommittedChanges: hasUncommitted,
+        });
         const detail = {
             agent_id: agent.agentId,
             agent_type: agent.agentType,
@@ -254,15 +286,13 @@ parentSessionId) {
             after: agent.after,
             task_type: agent.taskType,
             host: agent.hostName,
+            workspace_dir: agent.workspaceDir,
             failure: agent.failure,
             mode: agent.mode,
             cloud_session_id: agent.cloudSessionId,
             cloud_provider: agent.cloudProvider,
             pr_url: agent.prUrl,
-            delivery: resolveTeammateDelivery({
-                status: agent.status,
-                prUrl: agent.prUrl,
-            }),
+            delivery,
             files_created: delta.new_files_created,
             files_modified: delta.new_files_modified,
             files_read: delta.new_files_read,
@@ -297,7 +327,7 @@ export async function handleTasks(manager, limit = 10) {
     }
     const tasks = [];
     for (const [taskName, agents] of taskMap) {
-        let pending = 0, running = 0, completed = 0, failed = 0, stopped = 0;
+        let pending = 0, running = 0, completed = 0, stranded = 0, failed = 0, stopped = 0;
         let earliestStart = null;
         let latestActivity = null;
         let workspaceDir = null;
@@ -313,6 +343,19 @@ export async function handleTasks(manager, limit = 10) {
                 failed++;
             else if (agent.status === AgentStatus.STOPPED)
                 stopped++;
+            // Stranded = completed, no PR, local worktree still dirty. Probes the real
+            // worktree so `teams tasks` and `teams list --status` don't classify lost
+            // work as done (PHNX-2951).
+            if (agent.status === AgentStatus.COMPLETED && !agent.prUrl?.trim() && !agent.hostName && agent.workspaceDir) {
+                const delivery = resolveTeammateDelivery({
+                    status: agent.status,
+                    prUrl: agent.prUrl,
+                    hasUncommittedChanges: await hasUncommittedChanges(agent.workspaceDir),
+                });
+                if (delivery === 'stranded') {
+                    stranded++;
+                }
+            }
             // Track earliest start (created_at)
             if (!earliestStart || agent.startedAt < earliestStart) {
                 earliestStart = agent.startedAt;
@@ -336,6 +379,7 @@ export async function handleTasks(manager, limit = 10) {
             pending,
             running,
             completed,
+            stranded,
             failed,
             stopped,
             workspace_dir: workspaceDir,

package/dist/lib/teams/delivery.d.ts

@@ -12,13 +12,17 @@
  */
 import { AgentStatus } from './agents.js';
 /** Postcondition-facing delivery of a teammate's work. */
-export type TeammateDelivery = 'pending' | 'in_progress' | 'pr_open' | 'pr_merged' | 'no_pr' | 'failed' | 'stopped';
+export type TeammateDelivery = 'pending' | 'in_progress' | 'pr_open' | 'pr_merged' | 'no_pr' | 'stranded' | 'failed' | 'stopped';
 /**
  * Derive delivery from process status and PR state.
  *
  * When the process completed with a `prUrl` and merge is unknown or false,
  * delivery is `pr_open` — pessimistic: assume open until proven merged so an
  * orchestrator never mistakes "agent stopped" for "work on main".
+ *
+ * When the process completed with no PR and uncommitted changes remain in the
+ * worktree, delivery is `stranded` — the work exists only locally and will be
+ * lost if the worktree is cleaned up (PHNX-2951).
  */
 export declare function resolveTeammateDelivery(opts: {
     status: AgentStatus | string;
@@ -28,14 +32,20 @@ export declare function resolveTeammateDelivery(opts: {
      * `null`/`undefined` = unknown; with a `prUrl` that means `pr_open`.
      */
     prMerged?: boolean | null;
+    /**
+     * Whether the teammate's worktree has uncommitted changes. Only consulted
+     * when the process completed without a PR URL.
+     */
+    hasUncommittedChanges?: boolean | null;
 }): TeammateDelivery;
 /**
  * Human label for `teams status` rows. Replaces bare COMPLETED with PR OPEN
- * when delivery is still pending merge.
+ * when delivery is still pending merge, and with STRANDED when uncommitted
+ * work is stranded in the worktree.
  */
 export declare function deliveryDisplayLabel(delivery: TeammateDelivery, processStatus: AgentStatus | string): string;
 /**
- * Color key for statusColor-style switches. `pr_open` is its own key so the
- * row is visually distinct from green COMPLETED.
+ * Color key for statusColor-style switches. `pr_open` and `stranded` get their
+ * own keys so the rows are visually distinct from green COMPLETED.
  */
 export declare function deliveryColorKey(delivery: TeammateDelivery, processStatus: string): string;

package/dist/lib/teams/delivery.js

@@ -17,6 +17,10 @@ import { AgentStatus } from './agents.js';
  * When the process completed with a `prUrl` and merge is unknown or false,
  * delivery is `pr_open` — pessimistic: assume open until proven merged so an
  * orchestrator never mistakes "agent stopped" for "work on main".
+ *
+ * When the process completed with no PR and uncommitted changes remain in the
+ * worktree, delivery is `stranded` — the work exists only locally and will be
+ * lost if the worktree is cleaned up (PHNX-2951).
  */
 export function resolveTeammateDelivery(opts) {
     const status = String(opts.status);
@@ -30,8 +34,9 @@ export function resolveTeammateDelivery(opts) {
         return 'stopped';
     if (status === AgentStatus.COMPLETED || status === 'completed') {
         const prUrl = opts.prUrl?.trim();
-        if (!prUrl)
-            return 'no_pr';
+        if (!prUrl) {
+            return opts.hasUncommittedChanges ? 'stranded' : 'no_pr';
+        }
         if (opts.prMerged === true)
             return 'pr_merged';
         return 'pr_open';
@@ -40,21 +45,26 @@ export function resolveTeammateDelivery(opts) {
 }
 /**
  * Human label for `teams status` rows. Replaces bare COMPLETED with PR OPEN
- * when delivery is still pending merge.
+ * when delivery is still pending merge, and with STRANDED when uncommitted
+ * work is stranded in the worktree.
  */
 export function deliveryDisplayLabel(delivery, processStatus) {
     if (delivery === 'pr_open')
         return 'PR OPEN';
     if (delivery === 'pr_merged')
         return 'COMPLETED';
+    if (delivery === 'stranded')
+        return 'STRANDED';
     return String(processStatus).toUpperCase();
 }
 /**
- * Color key for statusColor-style switches. `pr_open` is its own key so the
- * row is visually distinct from green COMPLETED.
+ * Color key for statusColor-style switches. `pr_open` and `stranded` get their
+ * own keys so the rows are visually distinct from green COMPLETED.
  */
 export function deliveryColorKey(delivery, processStatus) {
     if (delivery === 'pr_open')
         return 'pr_open';
+    if (delivery === 'stranded')
+        return 'stranded';
     return String(processStatus);
 }

package/dist/lib/traces/schema2-build.d.ts

@@ -0,0 +1,85 @@
+/**
+ * schema2-build — the PRODUCER's per-tool mappers + `buildSessionDetailV2`
+ * (PHNX-3442 step 2, increments 2-4).
+ *
+ * Populates the `SessionStepV2` discriminated union (schema2.ts) from the parsed
+ * session events, reusing the SAME infrastructure the schema-1 path already uses:
+ *
+ *   - the callId pairing loop (`pairSteps` in session/trajectory.ts) — so a step's
+ *     (use event, result event) triple is recovered without a duplicate loop;
+ *   - bash unwrap/tokenize/classify (`session/bash-command.ts`) + the effective
+ *     program resolver (`effectiveProgram`);
+ *   - the meta / whereItWentWrong / surfacedToolFailures / active-time helpers
+ *     factored out of sync.ts (`buildDetailMeta`, `buildWhereItWentWrong`, …).
+ *
+ * The command/patch/output PARSING lives here; the worker stores the shard
+ * opaquely and the console reads the union directly and never reparses (spec §5).
+ *
+ * category / risk / categoryMetrics are DELIBERATELY omitted from the schema-2
+ * detail: the shipped consumer (`decodeSessionDetail` → coerceCategory/Risk/Metrics)
+ * backfills them to the same neutral defaults it uses for schema-1, so computing
+ * them here would be inventing session-level signal this step does not own.
+ */
+import { type BashCategory as ClassifierCategory } from '../session/bash-command.js';
+import { type SessionTrajectory } from '../session/trajectory.js';
+import type { SessionEvent } from '../session/types.js';
+import type { BashAction, BashCategory, SessionStepV2 } from './schema2.js';
+import { activeMsFromTrajectory, type SessionDetail } from './sync.js';
+/**
+ * SessionDetailV2 — the schema-2 shard this producer emits.
+ *
+ * `category` / `risk` / `categoryMetrics` are DELIBERATELY OMITTED. The consumer's
+ * `SessionDetailV2` declares them, but its `decodeSchema2` backfills neutral
+ * defaults via `coerceCategory`/`coerceRisk`/`coerceMetrics` (never throws) — the
+ * same defaulting it applies to schema-1 shards today. This producer does not yet
+ * author those fields (their provenance is the prix/api PHNX-3351 hosted backend,
+ * not agents-cli), so emitting them here would fabricate classification. Omission
+ * is the honest choice and is asserted as a tested contract in
+ * `schema2-fixture.test.ts`. Wire real category/risk here once its source is settled.
+ */
+export interface SessionDetailV2 {
+    schema: 2;
+    id: string;
+    meta: SessionDetail['meta'];
+    steps: SessionStepV2[];
+    gaps: SessionTrajectory['gaps'];
+    truncatedSteps: number;
+    whereItWentWrong: string | null;
+    surfacedToolFailures: Array<{
+        tool?: string;
+        label: string;
+        detail?: string;
+    }>;
+}
+/**
+ * `unwrapCommand` (bash-command.ts) strips VAR=/sudo/cd&&/npx/loops/subshells but
+ * NOT an interpreter wrapper like `/bin/zsh -lc "…"`, `bash -lc '…'`, or `sh -c …`
+ * — the exact shape the managed runner wraps every command in. Peel that first,
+ * then hand the inner payload to the existing unwrapper so all the wrappers it DOES
+ * know still apply. One extra rule, at the source, not a fork of unwrapCommand.
+ */
+export declare function unwrapShellExec(command: string): string;
+/**
+ * Map a classifier `BashCategory` (the rich vcs|build-test|install|… taxonomy) to
+ * the coarse schema-2 `BashCategory` (build|test|git|network|other). `build-test`
+ * needs the argv/subcommand to decide build vs test — `bun test` is test, `bun
+ * build` is build — so this takes the tokenized argv too.
+ */
+export declare function mapBashCategory(cat: ClassifierCategory, argv: string[]): BashCategory;
+/** Build the per-segment BashAction list for a bash command. */
+export declare function buildBashActions(unwrapped: string): BashAction[];
+export interface BuildDetailV2Options {
+    redact?: boolean;
+    knownSecrets?: readonly string[];
+}
+/**
+ * Build the schema-2 per-session detail from a pre-built trajectory and its raw
+ * events. The trajectory supplies meta/gaps/whereItWentWrong/surfacedToolFailures
+ * (via the shared sync.ts helpers) and the truncation count; the raw events supply
+ * the per-tool detail the schema-1 flat step could not carry.
+ *
+ * Re-pairs the events with `pairSteps` (the SAME loop buildTrajectory ran) to
+ * recover each step's (use event, result event) triple, then dispatches per tool.
+ */
+export declare function buildSessionDetailV2(traj: SessionTrajectory, events: SessionEvent[], options?: BuildDetailV2Options): SessionDetailV2;
+export { activeMsFromTrajectory };