@phnx-labs/agents-cli 1.20.5 → 1.20.6

package/README.md

@@ -243,7 +243,7 @@ agents teams status auth-feature    # Who's working, what they changed, what the
 
 Teammates run detached -- close your terminal, they keep working. Check in with `teams status`, read full output with `teams logs <name>`, clean up with `teams disband`.
 
-Team state is observable via `agents teams list --json` / `agents teams status --json`. External tools join it with `sessions --json` (teammates get `isTeamOrigin: true`) and `cloud list --json` (for `--cloud` teammates) to build a unified fleet view. See [docs/06-observability.md](docs/06-observability.md).
+Team state is observable via `agents teams list --json` / `agents teams status --json` (compact by default; add `--verbose` for the full per-teammate shape). External tools join it with `sessions --json` (teammates get `isTeamOrigin: true`) and `cloud list --json` (for `--cloud` teammates) to build a unified fleet view. See [docs/06-observability.md](docs/06-observability.md).
 
 ---
 

package/dist/commands/browser.js

@@ -1,7 +1,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { listProfiles, getProfile, createProfile, deleteProfile, ensureDefaultBrowserProfile, getProfileRuntimeDir, extractConfiguredPort, findFreeProfilePort, getEndpointPresets, } from '../lib/browser/profiles.js';
-import { findBrowserPath, getPortOccupant } from '../lib/browser/chrome.js';
+import { findBrowserPath, getPortOccupant, isLauncherScript } from '../lib/browser/chrome.js';
 import { listProfileCacheDirs, removeProfileCache, listAllProfileSnapshots, } from '../lib/browser/runtime-state.js';
 import { DEFAULT_VIEWPORT } from '../lib/browser/devices.js';
 import { discoverBrowserWsUrl, verifyBrowserIdentity } from '../lib/browser/cdp.js';
@@ -311,10 +311,28 @@ function registerProfilesCommands(browser) {
             process.exit(1);
         }
         const checks = [];
-        // 1. Binary exists for declared browser type
+        // 1. Binary exists for declared browser type, and is a real executable we
+        //    can drive — not a distro launcher script. findBrowserPath already
+        //    unwraps the known Chromium wrappers to their ELF; if it still hands
+        //    back a shebang script we couldn't resolve, `start` would fail with
+        //    `CDP connection closed` (the wrapper re-execs the browser as a child,
+        //    breaking the --remote-debugging-pipe transport — issue #229). Flag it
+        //    here instead of letting launch fail opaquely.
         try {
             const binPath = findBrowserPath(profile.browser, profile.binary);
-            checks.push({ label: 'binary', ok: true, detail: binPath });
+            if (isLauncherScript(binPath)) {
+                checks.push({
+                    label: 'binary',
+                    ok: false,
+                    detail: `${binPath} is a launcher script, not the browser executable — ` +
+                        `agents browser drives the browser over --remote-debugging-pipe and ` +
+                        `can't attach to a wrapper that re-execs it. Point the profile at the ` +
+                        `real binary (\`--binary /path/to/browser\`) or reinstall the standard package.`,
+                });
+            }
+            else {
+                checks.push({ label: 'binary', ok: true, detail: binPath });
+            }
         }
         catch (err) {
             checks.push({
@@ -351,7 +369,16 @@ function registerProfilesCommands(browser) {
         else {
             const occupant = getPortOccupant(port);
             if (!occupant) {
-                checks.push({ label: 'port', ok: true, detail: `${port} is free` });
+                // A free port doesn't mean "ready to launch here": for a local
+                // profile we self-launch over an internal --remote-debugging-pipe and
+                // never bind this port. The port is consulted only to attach to a
+                // browser someone already started on it. Say so, so a green doctor
+                // can't be read as "the port is what launch depends on" (#229).
+                checks.push({
+                    label: 'port',
+                    ok: true,
+                    detail: `${port} free — will self-launch over an internal pipe (port used only to attach to an already-running browser)`,
+                });
             }
             else {
                 try {

package/dist/commands/computer.js

@@ -12,8 +12,16 @@ const COMPUTER_HELP_GROUPS = [
 ];
 export function registerComputerCommand(program) {
     const computer = program
-        .command('computer')
-        .description('Drive macOS apps via Accessibility — list, screenshot, click, type');
+        .command('computers')
+        .description('Drive macOS apps via Accessibility — list, screenshot, click, type (macOS only)')
+        // The whole subsystem is macOS Accessibility / TCC. Fail fast with a clear
+        // message on other platforms instead of a downstream ENOENT / launchctl error.
+        .hook('preAction', () => {
+        if (process.platform !== 'darwin') {
+            console.error('agents computers: macOS only — it drives apps via the macOS Accessibility API.');
+            process.exit(1);
+        }
+    });
     registerComputerSubcommands(computer);
     registerCommandGroups(computer, COMPUTER_HELP_GROUPS);
 }

package/dist/commands/defaults.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Defaults command tree.
+ *
+ * `agents defaults run ...` manages selector-based defaults for `agents run`.
+ */
+import type { Command } from 'commander';
+export declare function registerDefaultsCommands(program: Command): void;

package/dist/commands/defaults.js

@@ -0,0 +1,89 @@
+/**
+ * Defaults command tree.
+ *
+ * `agents defaults run ...` manages selector-based defaults for `agents run`.
+ */
+import chalk from 'chalk';
+import { setHelpSections } from '../lib/help.js';
+import { listRunDefaults, setRunDefault, unsetRunDefault, } from '../lib/run-defaults.js';
+function formatRunDefault(entry) {
+    const parts = [];
+    if (entry.defaults.mode)
+        parts.push(`mode ${chalk.white(entry.defaults.mode)}`);
+    if (entry.defaults.model)
+        parts.push(`model ${chalk.white(entry.defaults.model)}`);
+    return `${chalk.cyan(entry.selector.padEnd(22))} ${parts.join('  ')}`;
+}
+export function registerDefaultsCommands(program) {
+    const defaults = program
+        .command('defaults')
+        .description('Manage default options for agents-cli commands');
+    const run = defaults
+        .command('run')
+        .description('Manage selector-based defaults for `agents run`');
+    setHelpSections(run, {
+        examples: `
+      agents defaults run list
+      agents defaults run set 'claude:*' --mode auto --model opus
+      agents defaults run set claude@2.1.45 --mode plan --model sonnet
+      agents defaults run unset 'claude:*'
+    `,
+        notes: `
+      Selectors use <agent>:<version>. Use * for all versions of an agent.
+      Exact selectors override wildcard selectors field by field.
+      Explicit flags on agents run always win over configured defaults.
+    `,
+    });
+    run
+        .command('list')
+        .description('List configured run defaults')
+        .action(() => {
+        const entries = listRunDefaults();
+        if (entries.length === 0) {
+            console.log(chalk.gray('No run defaults configured.'));
+            console.log(chalk.gray("Set one with: agents defaults run set 'claude:*' --mode auto --model opus"));
+            return;
+        }
+        console.log(chalk.bold('Run Defaults\n'));
+        for (const entry of entries) {
+            console.log(`  ${formatRunDefault(entry)}`);
+        }
+    });
+    run
+        .command('set <selector>')
+        .description('Set defaults for an agent/version selector')
+        .option('--mode <mode>', "Default mode: plan, edit, auto, skip. 'full' accepted as alias for skip.")
+        .option('--model <model>', 'Default model or model alias, forwarded via --model')
+        .action((selector, options) => {
+        try {
+            const entry = setRunDefault(selector, {
+                ...(options.mode !== undefined ? { mode: options.mode } : {}),
+                ...(options.model !== undefined ? { model: options.model } : {}),
+            });
+            console.log(chalk.green('Set run default:'));
+            console.log(`  ${formatRunDefault(entry)}`);
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exit(1);
+        }
+    });
+    run
+        .command('unset <selector>')
+        .description('Remove defaults for an agent/version selector')
+        .action((selector) => {
+        try {
+            const removed = unsetRunDefault(selector);
+            if (removed) {
+                console.log(chalk.green(`Removed run default ${selector}`));
+            }
+            else {
+                console.log(chalk.gray(`No run default matched ${selector}`));
+            }
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exit(1);
+        }
+    });
+}

package/dist/commands/exec.js

@@ -85,7 +85,7 @@ export function registerRunCommand(program) {
     `,
     });
     runCmd.action(async (agentSpec, prompt, options) => {
-        const [{ buildExecCommand, parseExecEnv, execAgent, runWithFallback, normalizeMode, resolveMode, defaultModeFor }, { ALL_AGENT_IDS }, { profileExists, resolveProfileForRun }, { readAndResolveBundleEnv, describeBundle }, { getConfiguredRunStrategy, normalizeRunStrategy, resolveRunVersion, RUN_STRATEGIES }, { getGlobalDefault, getVersionHomePath, resolveVersionAlias }, { buildDiscoveredPlugin, loadPluginManifest, syncPluginToVersion }, { parseWorkflowFrontmatter, resolveWorkflowRef },] = await Promise.all([
+        const [{ buildExecCommand, parseExecEnv, execAgent, runWithFallback, normalizeMode, resolveMode, defaultModeFor }, { ALL_AGENT_IDS }, { profileExists, resolveProfileForRun }, { readAndResolveBundleEnv, describeBundle }, { getConfiguredRunStrategy, normalizeRunStrategy, resolveRunVersion, RUN_STRATEGIES }, { getGlobalDefault, getVersionHomePath, resolveVersion, resolveVersionAlias }, { buildDiscoveredPlugin, loadPluginManifest, syncPluginToVersion }, { parseWorkflowFrontmatter, resolveWorkflowRef }, { resolveRunDefaults },] = await Promise.all([
             import('../lib/exec.js'),
             import('../lib/agents.js'),
             import('../lib/profiles.js'),
@@ -94,6 +94,7 @@ export function registerRunCommand(program) {
             import('../lib/versions.js'),
             import('../lib/plugins.js'),
             import('../lib/workflows.js'),
+            import('../lib/run-defaults.js'),
         ]);
         const isValidAgent = (agent) => ALL_AGENT_IDS.includes(agent);
         // Parse agent@version
@@ -102,6 +103,7 @@ export function registerRunCommand(program) {
         let version = rawVersion || undefined;
         let profileEnv;
         let fromProfile = false;
+        let workflowModel;
         const cwd = options.cwd ?? process.cwd();
         if (isValidAgent(rawAgent)) {
             agent = rawAgent;
@@ -133,6 +135,10 @@ export function registerRunCommand(program) {
             //   subagents/*.md     ← flat .md files copied to ~/.claude/agents/ for Agent tool discovery
             const workflowDir = resolveWorkflowRef(rawAgent, cwd);
             agent = 'claude';
+            const workflowFrontmatter = parseWorkflowFrontmatter(workflowDir);
+            if (typeof workflowFrontmatter?.model === 'string' && workflowFrontmatter.model.trim() !== '') {
+                workflowModel = workflowFrontmatter.model.trim();
+            }
             const resolvedVersion = resolveVersionAlias('claude', version);
             const versionHome = getVersionHomePath('claude', resolvedVersion ?? getGlobalDefault('claude') ?? '');
             const claudeAgentsDir = path.join(versionHome, '.claude', 'agents');
@@ -179,8 +185,7 @@ export function registerRunCommand(program) {
             // Auto-inject secrets bundles declared in the workflow's frontmatter `secrets:` field.
             // Union with any --secrets flags the user passed; dedupe. Skip when --no-auto-secrets is set.
             if (!options.noAutoSecrets) {
-                const fm = parseWorkflowFrontmatter(workflowDir);
-                const declared = fm?.secrets ?? [];
+                const declared = workflowFrontmatter?.secrets ?? [];
                 if (declared.length > 0) {
                     const existing = new Set(options.secrets);
                     const added = [];
@@ -262,9 +267,18 @@ export function registerRunCommand(program) {
                 }
             }
         }
+        const defaultVersion = version ?? resolveVersion(agent, cwd);
+        const runDefaults = fromProfile
+            ? { sources: {} }
+            : resolveRunDefaults(agent, defaultVersion, cwd);
         // Accept the four canonical modes plus 'full' as a permanent silent
         // alias for 'skip' (rewritten downstream by normalizeMode in exec.ts).
         let mode = options.mode;
+        const modeSource = runCmd.getOptionValueSource('mode');
+        const modeFromRunDefault = modeSource === 'default' && !!runDefaults.mode;
+        if (modeFromRunDefault) {
+            mode = runDefaults.mode;
+        }
         if (!['plan', 'edit', 'auto', 'skip', 'full'].includes(mode)) {
             console.error(chalk.red(`Invalid mode: ${mode}. Use plan, edit, auto, or skip ('full' accepted as alias for skip).`));
             process.exit(1);
@@ -276,13 +290,12 @@ export function registerRunCommand(program) {
         // user did not ask for read-only, they asked for "just run it." An
         // explicit --mode plan still throws (see resolveMode), because silently
         // elevating an explicit read-only request to edit is unsafe.
-        const modeSource = runCmd.getOptionValueSource('mode');
         const modeIsDefault = modeSource === 'default';
         try {
             resolveMode(agent, normalizeMode(mode));
         }
         catch (err) {
-            if (modeIsDefault) {
+            if (modeIsDefault && !modeFromRunDefault) {
                 mode = defaultModeFor(agent);
                 if (!options.quiet) {
                     process.stderr.write(chalk.gray(`[agents] ${agent} has no '${options.mode}' mode; using '${mode}'\n`));
@@ -334,6 +347,11 @@ export function registerRunCommand(program) {
         const env = hasOverrides
             ? { ...(profileEnv ?? {}), ...secretsEnv, ...(userEnv ?? {}) }
             : undefined;
+        const modelSource = runCmd.getOptionValueSource('model');
+        const model = options.model
+            ?? (!fromProfile && modelSource === undefined
+                ? (workflowModel ?? (options.fallback ? undefined : runDefaults.model))
+                : undefined);
         const execOptions = {
             agent,
             version,
@@ -342,7 +360,7 @@ export function registerRunCommand(program) {
             mode,
             effort,
             cwd: options.cwd,
-            model: options.model,
+            model,
             addDirs: options.addDir,
             json: options.json,
             headless: options.headless ?? true,

package/dist/commands/rules.js

@@ -4,7 +4,7 @@ import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
 import { select, checkbox } from '@inquirer/prompts';
-import { AGENTS, ALL_AGENT_IDS, resolveAgentName, formatAgentError, agentLabel, } from '../lib/agents.js';
+import { AGENTS, agentConfigDirName, ALL_AGENT_IDS, resolveAgentName, formatAgentError, agentLabel, } from '../lib/agents.js';
 import { cloneRepo } from '../lib/git.js';
 import { discoverInstructionsFromRepo, discoverRuleFilesFromRepo, installInstructionsCentrally, uninstallInstructions, listInstalledInstructionsWithScope, instructionsExists, getInstructionsContent, listCentralRules, } from '../lib/rules/rules.js';
 import { listInstalledVersions, getGlobalDefault, resolveVersionAlias, syncResourcesToVersion, promptAgentVersionSelection, getVersionHomePath, } from '../lib/versions.js';
@@ -426,7 +426,7 @@ Examples:
                 return;
             }
             const home = getVersionHomePath(agentId, requestedVersion);
-            const filePath = path.join(home, `.${agentId}`, AGENTS[agentId].instructionsFile);
+            const filePath = path.join(home, agentConfigDirName(agentId), AGENTS[agentId].instructionsFile);
             if (!fs.existsSync(filePath)) {
                 console.log(chalk.yellow(`No user rules found for ${agentLabel(agentId)}@${requestedVersion}`));
                 return;
@@ -486,7 +486,7 @@ Examples:
             }
             const home = getVersionHomePath(agentId, requestedVersion);
             const agent = AGENTS[agentId];
-            const filePath = path.join(home, `.${agentId}`, agent.instructionsFile);
+            const filePath = path.join(home, agentConfigDirName(agentId), agent.instructionsFile);
             if (fs.existsSync(filePath)) {
                 fs.unlinkSync(filePath);
                 console.log(chalk.green(`Removed ${agent.instructionsFile} from ${agentLabel(agent.id)}@${requestedVersion}`));

package/dist/commands/secrets.js

@@ -1052,15 +1052,15 @@ Examples:
             password += charClass[charIndex];
         }
         if (opts.copy) {
-            const { spawn } = await import('child_process');
-            const proc = spawn('pbcopy', [], { stdio: ['pipe', 'inherit', 'inherit'] });
-            proc.stdin.write(password);
-            proc.stdin.end();
-            await new Promise((resolve, reject) => {
-                proc.on('close', (code) => code === 0 ? resolve() : reject(new Error('pbcopy failed')));
-                proc.on('error', reject);
-            });
-            console.log(chalk.green(`Password copied to clipboard (${length} chars)`));
+            try {
+                await copyToClipboard(password);
+                console.log(chalk.green(`Password copied to clipboard (${length} chars)`));
+            }
+            catch (err) {
+                console.error(chalk.red(`Clipboard copy failed: ${err.message}`));
+                console.error(chalk.gray('Re-run without --copy to print the password instead.'));
+                process.exitCode = 1;
+            }
         }
         else {
             console.log(password);
@@ -1069,3 +1069,40 @@ Examples:
     registerSecretsSyncCommands(cmd);
     registerSecretsMigrateAclCommand(cmd);
 }
+/**
+ * Copy text to the system clipboard, cross-platform.
+ * macOS: `pbcopy`. Windows: `clip`. Linux: tries `wl-copy` (Wayland), then
+ * `xclip`, then `xsel` (X11). Throws with an install hint if none are present.
+ */
+async function copyToClipboard(text) {
+    const { spawn } = await import('child_process');
+    const candidates = process.platform === 'darwin'
+        ? [['pbcopy', []]]
+        : process.platform === 'win32'
+            ? [['clip', []]]
+            : [
+                ['wl-copy', []],
+                ['xclip', ['-selection', 'clipboard']],
+                ['xsel', ['--clipboard', '--input']],
+            ];
+    let lastErr = null;
+    for (const [cmd, args] of candidates) {
+        try {
+            await new Promise((resolve, reject) => {
+                const proc = spawn(cmd, args, { stdio: ['pipe', 'ignore', 'ignore'] });
+                proc.on('error', reject);
+                proc.on('close', (code) => (code === 0 ? resolve() : reject(new Error(`${cmd} exited ${code}`))));
+                proc.stdin.write(text);
+                proc.stdin.end();
+            });
+            return;
+        }
+        catch (err) {
+            lastErr = err;
+        }
+    }
+    const hint = process.platform === 'linux'
+        ? ' Install one: wl-clipboard (Wayland) or xclip / xsel (X11).'
+        : '';
+    throw new Error(`no clipboard tool available (${lastErr?.message ?? 'none found'}).${hint}`);
+}

package/dist/commands/setup.js

@@ -14,7 +14,7 @@ import { DEFAULT_SYSTEM_REPO, systemRepoSlug } from '../lib/types.js';
 import { getAgentsDir, getVersionsDir, ensureAgentsDir } from '../lib/state.js';
 import { isGitRepo, cloneIntoExisting, pullRepo } from '../lib/git.js';
 import { isPromptCancelled, isInteractiveTerminal } from './utils.js';
-import { AGENTS, getUnmanagedAgentInstalls, countSessionFiles, agentLabel } from '../lib/agents.js';
+import { AGENTS, agentConfigDirName, getUnmanagedAgentInstalls, countSessionFiles, agentLabel } from '../lib/agents.js';
 import { setGlobalDefault } from '../lib/versions.js';
 import { ensureShimCurrent, switchHomeFileSymlinks, isShimsInPath, addShimsToPath, getPathSetupInstructions } from '../lib/shims.js';
 import { setHelpSections } from '../lib/help.js';
@@ -28,7 +28,7 @@ async function importAgent(agentId, version) {
     const configDir = agent.configDir;
     const versionsDir = getVersionsDir();
     const versionHome = path.join(versionsDir, agentId, version, 'home');
-    const versionConfigDir = path.join(versionHome, `.${agentId}`);
+    const versionConfigDir = path.join(versionHome, agentConfigDirName(agentId));
     // Skip if version dir already exists (collision)
     if (fs.existsSync(versionConfigDir)) {
         return { success: false, skipped: true, error: `${version} already installed` };

package/dist/commands/teams.js

@@ -4,7 +4,7 @@ import * as path from 'path';
 import { AgentManager, checkAllClis, getAgentsDir, VALID_TASK_TYPES, } from '../lib/teams/agents.js';
 import { resolveProvider } from '../lib/cloud/registry.js';
 import { runSupervisor } from '../lib/teams/supervisor.js';
-import { handleSpawn, handleStatus, handleStop, handleTasks, } from '../lib/teams/api.js';
+import { handleSpawn, handleStatus, handleStop, handleTasks, toTaskStatusSummary, } from '../lib/teams/api.js';
 import { createTeam, ensureTeam, getTeam, loadTeams, removeTeam, teamExists, } from '../lib/teams/registry.js';
 import { setHelpSections } from '../lib/help.js';
 import { createWorktree, isGitRepo, hasUncommittedChanges, removeWorktree, } from '../lib/teams/worktree.js';
@@ -382,6 +382,55 @@ async function resolveTeammateSessions(agents) {
     }
     return map;
 }
+// Default compact renderer — one block per teammate, optimized for the
+// orchestrator scanning "what state, what did you touch, what did you say
+// last." Caller passes the projected AgentStatusSummary; for the full
+// verbose layout use printAgentDetail above.
+function printAgentSummary(s) {
+    const label = statusColor(s.status)(s.status.toUpperCase());
+    const handle = s.name ?? shortId(s.agent_id);
+    const ident = s.name ? chalk.gray(`(${shortId(s.agent_id)})`) : '';
+    const duration = s.duration ? `${chalk.gray(' · ')}${chalk.white(s.duration)}` : '';
+    const errBadge = s.has_errors ? chalk.red(' !') : '';
+    const tools = chalk.gray(` · ${s.tool_count} tools`);
+    console.log(`  ${chalk.cyan(handle.padEnd(14))} ${ident.padEnd(11)} ${label}${duration}${tools}${errBadge}`);
+    // Files: counts + basenames. Read is count only.
+    const fileLines = [];
+    const renderCat = (label, cat) => {
+        if (cat.count === 0)
+            return;
+        const more = cat.count > cat.names.length ? ` +${cat.count - cat.names.length}` : '';
+        const names = cat.names.length ? ` ${cat.names.join(', ')}${more}` : '';
+        fileLines.push(`${label} ${cat.count}${names}`);
+    };
+    renderCat('modified', s.files.modified);
+    renderCat('created', s.files.created);
+    renderCat('deleted', s.files.deleted);
+    if (s.files.read.count > 0)
+        fileLines.push(`read ${s.files.read.count}`);
+    if (fileLines.length) {
+        console.log(`    ${chalk.gray('files   ')} ${fileLines.join(chalk.gray(' · '))}`);
+    }
+    // Last 3 bash commands.
+    const recentBash = s.bash_commands.slice(-3);
+    if (recentBash.length) {
+        console.log(`    ${chalk.gray('bash    ')}`);
+        for (const cmd of recentBash) {
+            console.log(`      ${chalk.gray('$')} ${truncate(cmd, 96)}`);
+        }
+    }
+    // Last messages — first non-empty line of each, truncated.
+    if (s.last_messages.length) {
+        console.log(`    ${chalk.gray('messages')}`);
+        for (const msg of s.last_messages) {
+            const firstLine = msg.split(/\r?\n/).find((l) => l.trim()) || '';
+            if (firstLine)
+                console.log(`      ${chalk.gray('>')} ${truncate(firstLine, 96)}`);
+        }
+    }
+    if (s.pr_url)
+        console.log(`    ${chalk.gray('PR      ')} ${chalk.cyan(s.pr_url)}`);
+}
 // Render a team's status in the same format the `status` subcommand uses, so
 // the interactive picker's Enter action drops the user into a familiar view.
 async function printTeamStatus(team, result) {
@@ -409,6 +458,36 @@ async function printTeamStatus(team, result) {
     console.log();
     console.log(chalk.gray(`cursor: ${result.cursor}`));
 }
+// Compact default renderer — no session-file dive, no per-teammate
+// 15-line preview. One block per teammate, suitable for the orchestrator
+// scanning what each agent did. Use `printTeamStatus` (above) for the
+// verbose/legacy layout.
+function printTeamSummary(team, result) {
+    const { summary, agents } = result;
+    console.log(chalk.bold(`Team ${chalk.cyan(team)}  `) +
+        chalk.gray(summary.pending > 0
+            ? `(${summary.pending} pending, ${summary.running} working, ${summary.completed} done, ${summary.failed} failed, ${summary.stopped} stopped)`
+            : `(${summary.running} working, ${summary.completed} done, ${summary.failed} failed, ${summary.stopped} stopped)`));
+    if (agents.length === 0) {
+        console.log(chalk.gray('  (no teammates yet — add one with `agents teams add`)'));
+    }
+    else {
+        const width = Math.min(process.stdout.columns || 80, 80);
+        const divider = chalk.gray('┈'.repeat(width));
+        for (let i = 0; i < agents.length; i++) {
+            console.log();
+            if (i > 0) {
+                console.log(divider);
+                console.log();
+            }
+            printAgentSummary(agents[i]);
+        }
+    }
+    console.log();
+    console.log(chalk.gray(`cursor: ${result.cursor}`));
+    console.log(chalk.gray('Full detail: agents teams status ' + team + ' --verbose'));
+    console.log(chalk.gray('Raw log:     agents teams logs --team ' + team + ' --teammate <name>'));
+}
 // Classify a team into a single bucket for --status filtering.
 //  - empty:   no teammates (created but nobody added yet)
 //  - waiting: only staged teammates — call `teams start` to kick them off
@@ -964,10 +1043,11 @@ export function registerTeamsCommands(program) {
     teams
         .command('status [team]')
         .aliases(['s', 'st', 'check'])
-        .description("Check in on a team: who's working, what files they touched, recent commands, last output. Pass --since for efficient delta polling.")
+        .description("Check in on a team: status, files touched, recent commands, last messages. Pass --verbose for the full per-teammate dump; --since for delta polling.")
         .option('-f, --filter <state>', 'Show only teammates in this state: running, completed, failed, stopped, or all (default: all)', 'all')
         .option('-s, --since <iso>', 'Cursor from a previous status call; only show updates after this timestamp (enables efficient polling)')
         .option('--agent-id <id>', 'Show only this one teammate (by UUID or UUID prefix)')
+        .option('-v, --verbose', 'Emit the full per-teammate detail (prompt, all file paths, all messages). Default is a compact summary.')
         .option('--json', 'Output machine-readable JSON')
         .action(async (team, opts) => {
         const filter = opts.filter;
@@ -984,8 +1064,15 @@ export function registerTeamsCommands(program) {
             const agents = opts.agentId
                 ? result.agents.filter((a) => a.agent_id.startsWith(opts.agentId))
                 : result.agents;
+            const filtered = { ...result, agents };
             if (isJsonMode(opts)) {
-                console.log(JSON.stringify({ ...result, agents }, null, 2));
+                // JSON output also respects --verbose. Default = compact summary
+                // shape; --verbose = full AgentStatusDetail. Same toggle covers
+                // both text and JSON so MCP-style consumers can opt into detail.
+                const payload = opts.verbose
+                    ? filtered
+                    : toTaskStatusSummary(filtered);
+                console.log(JSON.stringify(payload, null, 2));
                 return;
             }
             const exists = await teamExists(team);
@@ -993,7 +1080,12 @@ export function registerTeamsCommands(program) {
                 console.log(chalk.yellow(`No team called '${team}'. Create it with: agents teams create ${team}`));
                 return;
             }
-            await printTeamStatus(team, { ...result, agents });
+            if (opts.verbose) {
+                await printTeamStatus(team, filtered);
+            }
+            else {
+                printTeamSummary(team, toTaskStatusSummary(filtered));
+            }
         }
         catch (err) {
             die(`Could not check on team ${team}: ${err.message}`);
@@ -1308,14 +1400,19 @@ export function registerTeamsCommands(program) {
     teams
         .command('logs [teammate]')
         .alias('log')
-        .description("Read a teammate's raw log output. Accepts name, UUID, or UUID prefix.")
+        .description("Read a teammate's raw log output. Accepts positional name, --teammate <name>, UUID, or UUID prefix.")
         .option('-n, --tail <n>', 'Show only the last N lines instead of the full log')
         .option('--team <team>', 'Disambiguate when the same name appears in multiple teams')
+        .option('--teammate <name>', 'Teammate name (alias for the positional arg; useful for scripts)')
         .action(async (ref, opts) => {
         const base = await getAgentsDir();
-        // No teammate → picker in TTY, hard fail outside.
+        // Resolve teammate identity. Precedence:
+        //   1. positional `[teammate]` arg (back-compat, most common)
+        //   2. --teammate <name> flag (script-friendly alias)
+        //   3. interactive picker (TTY only)
+        const teammateRef = ref ?? opts.teammate;
         let agentId;
-        if (!ref) {
+        if (!teammateRef) {
             const mgr = mkManager();
             const picked = await pickTeammateOr(mgr, 'agents teams logs');
             if (!picked)
@@ -1323,13 +1420,13 @@ export function registerTeamsCommands(program) {
             agentId = picked.agentId;
         }
         else {
-            const resolved = await resolveTeammateAcrossTeams(base, ref, opts.team);
+            const resolved = await resolveTeammateAcrossTeams(base, teammateRef, opts.team);
             if (resolved.kind === 'none') {
-                die(`No notes on record for teammate '${ref}'`, 2);
+                die(`No notes on record for teammate '${teammateRef}'`, 2);
             }
             if (resolved.kind === 'ambiguous') {
                 const hints = resolved.candidates.map((c) => `${c.team}/${c.display}`).join(', ');
-                die(`'${ref}' matches multiple teammates: ${hints}.\n` +
+                die(`'${teammateRef}' matches multiple teammates: ${hints}.\n` +
                     `  Narrow it with --team <team>, or pass a UUID prefix.`, 2);
             }
             agentId = resolved.agentId;
@@ -1346,7 +1443,7 @@ export function registerTeamsCommands(program) {
             process.stdout.write(lines.slice(-n).join('\n'));
         }
         catch {
-            die(`No notes on record for teammate '${ref ?? agentId}' (looked in ${logPath})`, 2);
+            die(`No notes on record for teammate '${teammateRef ?? agentId}' (looked in ${logPath})`, 2);
         }
     });
     // doctor

package/dist/commands/view.d.ts

@@ -9,6 +9,17 @@
 import type { Command } from 'commander';
 import type { AgentId } from '../lib/types.js';
 import { type ProfileSummary } from '../lib/profiles.js';
+/** Per-section filter flags. When any are true, only those sections render. */
+export interface ViewSectionFilter {
+    commands?: boolean;
+    skills?: boolean;
+    mcp?: boolean;
+    workflows?: boolean;
+    plugins?: boolean;
+    rules?: boolean;
+    hooks?: boolean;
+    promptcuts?: boolean;
+}
 /** Machine-readable entry for a single installed version. */
 export interface ViewJsonVersion {
     version: string;
@@ -54,6 +65,6 @@ export declare function viewAction(agentArg?: string, options?: {
     prune?: boolean;
     yes?: boolean;
     dryRun?: boolean;
-}): Promise<void>;
+} & ViewSectionFilter): Promise<void>;
 /** Register the `agents view` command. */
 export declare function registerViewCommand(program: Command): void;