feat(pilotctl): agent-first CLI overhaul — bounded output, filters, styling

Inbox was unusable for agents (23 MB --json dumps, oldest-first, 80-char
mid-token truncation) and several commands shared the same disease. This
makes every high-traffic command bounded, filterable, non-interactive,
and visually scannable, without breaking --json consumers.

- inbox: newest-first, default --limit 10, --latest/--from/--since/
  --full/read <id>/--clear --before; --json bounded (23 MB -> 3 KB)
- received: same flag surface ported (mtime-ordered; sender metadata
  unavailable in dataexchange filenames)
- peers: summary + exceptions-only view (surfaces unencrypted peers),
  colorized --all, --limit/--search
- trust: newest-first, --limit 20, --search, one-way trust flagged
- daemon status: fix contradiction (stale PID file reported "stopped"
  while live socket data printed); socket is now the source of truth
- info: grouped identity/network/traffic/skills layout
- ping: 5s default timeout (was 30s), relay-convergence hint on failure
- send-message/ping --json: add "to" resolved-address field
- send-message --wait, ping, bench, traceroute: animated elapsed line on
  stderr (TTY-only, erased on completion, no-op for pipes/--json)
- config/skills status/updates/network list: aligned key-value, per-tool
  status dots, word-boundary wrap, dead MEMBERS column dropped
- handshake/approve/untrust: next-step hints
- context <command>: single-command spec (18 KB -> ~440 B)

New style layer (cmd/pilotctl/style.go): semantic ANSI helpers gated on
TTY + NO_COLOR/PILOT_NO_COLOR/TERM=dumb; tests pipe stdout so assertions
stay plain-text.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: teovl

cmd/pilotctl/main.go

@@ -58,9 +58,11 @@ func runTick() (*skillinject.Report, error) {
 }
 
 // cmdSkillsStatus runs one tick (fetching the manifest + entrypoint over
-// HTTPS) and prints what state each managed file is in and what action
-// the daemon's next live tick would take.
-func cmdSkillsStatus(_ []string) {
+// HTTPS) and prints a per-tool summary line (statusDot + what, if anything,
+// the next tick would change). Per-file detail lines are behind --verbose.
+func cmdSkillsStatus(args []string) {
+	flags, _ := parseFlags(args)
+	verbose := flagBool(flags, "verbose")
 	report, err := runTick()
 	if err != nil {
 		fatalCode("internal", "skills tick: %v", err)
@@ -87,10 +89,8 @@ func cmdSkillsStatus(_ []string) {
 		return
 	}
 
-	fmt.Println("Pilot Protocol skill — install status")
-	fmt.Println("=====================================")
-	fmt.Printf("Reconcile cadence: every %s (default), plus once on daemon startup.\n", skillinject.DefaultInterval)
-	fmt.Println("All paths below are auto-managed by the daemon — edits are reverted on next tick.")
+	fmt.Println(sBold("Pilot Protocol skill — install status"))
+	fmt.Println(sDim(fmt.Sprintf("Reconcile cadence: every %s (default), plus once on daemon startup · paths are auto-managed — manual edits revert on next tick", skillinject.DefaultInterval)))
 	fmt.Println()
 
 	if len(report.Outcomes) == 0 {
@@ -116,8 +116,28 @@ func cmdSkillsStatus(_ []string) {
 	sort.Strings(tools)
 
 	for _, tool := range tools {
-		fmt.Printf("[%s]\n", tool)
-		for _, o := range byTool[tool] {
+		outs := byTool[tool]
+		// One summary line per tool: ok when every managed file is
+		// identical; otherwise warn naming the first offending file and
+		// the action the daemon's next tick will take; err on tick errors.
+		dot, summary := "ok", "skill+heartbeat ok"
+		for _, o := range outs {
+			if o.Err != "" {
+				dot = "err"
+				summary = fmt.Sprintf("%s — %s", filepath.Base(o.Path), o.Err)
+				break
+			}
+			if o.State != skillinject.StateIdentical && dot == "ok" {
+				dot = "warn"
+				summary = fmt.Sprintf("%s %s — next: %s", filepath.Base(o.Path), o.State, o.Action)
+			}
+		}
+		fmt.Printf("%s %s %s\n", statusDot(dot), sBold(tool), sDim(summary))
+
+		if !verbose {
+			continue
+		}
+		for _, o := range outs {
 			label := "skill copy:        "
 			switch o.Kind {
 			case skillinject.KindMarker:
@@ -138,6 +158,9 @@ func cmdSkillsStatus(_ []string) {
 		fmt.Println()
 	}
 
+	if !verbose {
+		fmt.Printf("\n%s\n", sDim("per-file detail: --verbose · paths only: pilotctl skills paths · force a pass: pilotctl skills check"))
+	}
 	if len(report.Skipped) > 0 {
 		fmt.Printf("Not installed (skipped): %s\n", strings.Join(report.Skipped, ", "))
 	}
@@ -361,18 +384,37 @@ func cmdSkillsEnable(args []string) {
 	}
 }
 
-// printSkillInstallSummary is called from cmdInfo to surface the agent
-// skill install paths in the standard daemon diagnostic. Quiet (no header)
-// when no agent tools are detected on the host.
+// skillInstallTools returns the agent tools that have the pilot skill
+// installed, in detection order. Empty when no agent tools are present
+// on the host. Same data source as `pilotctl skills`, collapsed to one
+// entry per tool.
+func skillInstallTools() []string {
+	report, err := runTick()
+	if err != nil || report == nil || len(report.Outcomes) == 0 {
+		return nil
+	}
+	seen := map[string]bool{}
+	var order []string
+	for _, o := range report.Outcomes {
+		if o.Kind != skillinject.KindSkill {
+			continue
+		}
+		if !seen[o.Tool] {
+			seen[o.Tool] = true
+			order = append(order, o.Tool)
+		}
+	}
+	return order
+}
+
+// printSkillInstallSummary surfaces the agent skill install paths.
+// Quiet (no header) when no agent tools are detected on the host.
 func printSkillInstallSummary() {
 	report, err := runTick()
 	if err != nil || report == nil || len(report.Outcomes) == 0 {
 		return
 	}
 	// Collapse to one path per tool: prefer the skill copy over the marker.
-	type entry struct {
-		Tool, Path string
-	}
 	seen := map[string]string{}
 	order := []string{}
 	for _, o := range report.Outcomes {

cmd/pilotctl/skills.go

@@ -0,0 +1,140 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+// style.go — ANSI styling for human-facing output.
+//
+// Rules:
+//   - Color only when stdout is a TTY and NO_COLOR / TERM=dumb are unset.
+//   - --json output is NEVER styled (agents parse it byte-for-byte).
+//   - Piped text output stays plain so grep/awk/cut keep working.
+//
+// The palette is semantic, not decorative: ok=green, warn=yellow,
+// err=red, accent=cyan (ids, hostnames), dim=metadata. Use sparingly —
+// a screen that is all color is as unreadable as one with none.
+
+package main
+
+import (
+	"fmt"
+	"os"
+	"sync"
+	"time"
+)
+
+// colorEnabled is computed once at startup. Tests capture stdout via a
+// pipe, so styling is automatically off there and assertions on plain
+// text stay stable.
+var colorEnabled = func() bool {
+	if os.Getenv("NO_COLOR") != "" || os.Getenv("PILOT_NO_COLOR") != "" {
+		return false
+	}
+	if os.Getenv("TERM") == "dumb" {
+		return false
+	}
+	fi, err := os.Stdout.Stat()
+	if err != nil {
+		return false
+	}
+	return fi.Mode()&os.ModeCharDevice != 0
+}()
+
+func sc(code, s string) string {
+	if !colorEnabled {
+		return s
+	}
+	return "\x1b[" + code + "m" + s + "\x1b[0m"
+}
+
+func sBold(s string) string   { return sc("1", s) }
+func sDim(s string) string    { return sc("2", s) }
+func sOK(s string) string     { return sc("32", s) }
+func sWarn(s string) string   { return sc("33", s) }
+func sErr(s string) string    { return sc("31", s) }
+func sAccent(s string) string { return sc("36", s) }
+
+// stderrIsTTY mirrors colorEnabled but for os.Stderr. It gates the
+// animated wait-progress line: animation (cursor rewrites) only makes
+// sense on an interactive terminal, and NO_COLOR / TERM=dumb users have
+// asked for plain output, so they get silence instead of a spinner.
+var stderrIsTTY = func() bool {
+	if os.Getenv("NO_COLOR") != "" || os.Getenv("PILOT_NO_COLOR") != "" {
+		return false
+	}
+	if os.Getenv("TERM") == "dumb" {
+		return false
+	}
+	fi, err := os.Stderr.Stat()
+	if err != nil {
+		return false
+	}
+	return fi.Mode()&os.ModeCharDevice != 0
+}()
+
+// startWaitProgress shows a single self-rewriting stderr line
+// ("label… Ns") while a blocking wait is in flight, so commands like
+// `send-message --wait` don't sit in 30 s of dead silence. Returns a
+// stop func that erases the line and terminates the ticker goroutine.
+//
+// Safe by construction:
+//   - no-op when stderr is not a TTY or --json is set (agents and pipes
+//     never see control sequences);
+//   - stop() is idempotent (sync.Once), so it can be called on every
+//     exit path of a wait without bookkeeping;
+//   - stop() blocks until the goroutine has erased the line, so output
+//     printed right after stop() never interleaves with the animation.
+//
+// First draw happens at the first 500 ms tick — sub-500 ms waits finish
+// without any flicker.
+func startWaitProgress(label string) (stop func()) {
+	if !stderrIsTTY || jsonOutput {
+		return func() {}
+	}
+	done := make(chan struct{})
+	finished := make(chan struct{})
+	start := time.Now()
+	go func() {
+		defer close(finished)
+		ticker := time.NewTicker(500 * time.Millisecond)
+		defer ticker.Stop()
+		for {
+			select {
+			case <-done:
+				fmt.Fprint(os.Stderr, "\r\x1b[2K")
+				return
+			case <-ticker.C:
+				elapsed := int(time.Since(start).Seconds())
+				fmt.Fprintf(os.Stderr, "\r\x1b[2K%s",
+					sDim(fmt.Sprintf("%s… %ds", label, elapsed)))
+			}
+		}
+	}()
+	var once sync.Once
+	return func() {
+		once.Do(func() {
+			close(done)
+			<-finished
+		})
+	}
+}
+
+// statusDot renders a colored ● for state lines: ok=green, warn=yellow,
+// err=red. Falls back to plain symbols when color is off so piped output
+// still distinguishes states.
+func statusDot(state string) string {
+	switch state {
+	case "ok":
+		if colorEnabled {
+			return sOK("●")
+		}
+		return "●"
+	case "warn":
+		if colorEnabled {
+			return sWarn("●")
+		}
+		return "◐"
+	default:
+		if colorEnabled {
+			return sErr("●")
+		}
+		return "○"
+	}
+}

cmd/pilotctl/style.go

@@ -114,24 +114,53 @@ func cmdUpdates(args []string) {
 			date = t.Format("2006-01-02")
 		}
 		title := strings.TrimSpace(it.Title)
-		fmt.Printf("• %s  %s\n", date, title)
+		fmt.Printf("• %s  %s\n", sAccent(date), title)
 		if len(it.Categories) > 0 {
-			fmt.Printf("    [%s]\n", strings.Join(it.Categories, ", "))
+			fmt.Printf("    %s\n", sDim("["+strings.Join(it.Categories, ", ")+"]"))
 		}
 		if d := strings.TrimSpace(it.Description); d != "" {
-			d = collapseWhitespace(d)
-			if len(d) > 200 {
-				d = d[:197] + "..."
-			}
-			fmt.Printf("    %s\n", d)
+			fmt.Printf("    %s\n", wrapText(collapseWhitespace(d), 100, 4))
 		}
 		if l := strings.TrimSpace(it.Link); l != "" {
-			fmt.Printf("    %s\n", l)
+			fmt.Printf("    %s\n", sDim(l))
 		}
 		fmt.Println()
 	}
 }
 
+// wrapText word-wraps s at word boundaries so no line exceeds width
+// columns (counting the indent), with a hanging indent: continuation
+// lines are prefixed with `indent` spaces to line up under a first line
+// the caller has already indented by the same amount. Words longer than
+// a full line are emitted unbroken — never split mid-word.
+func wrapText(s string, width, indent int) string {
+	words := strings.Fields(s)
+	if len(words) == 0 {
+		return ""
+	}
+	pad := strings.Repeat(" ", indent)
+	var b strings.Builder
+	lineLen := indent // caller prints the first line's indent
+	for i, w := range words {
+		wl := len([]rune(w))
+		switch {
+		case i == 0:
+			b.WriteString(w)
+			lineLen += wl
+		case lineLen+1+wl > width:
+			b.WriteString("\n")
+			b.WriteString(pad)
+			b.WriteString(w)
+			lineLen = indent + wl
+		default:
+			b.WriteString(" ")
+			b.WriteString(w)
+			lineLen += 1 + wl
+		}
+	}
+	return b.String()
+}
+
 // filterAndTruncate applies the --scope category filter (case-insensitive,
 // match-any-category) and the --count cap to a list of feed items. Both
 // arguments are inert when zero/empty, so callers can pass scope="" or