@saadnvd1/agent-os 0.3.728 → 0.3.733

package/components/SessionList/useGroupDrag.ts

@@ -0,0 +1,83 @@
+import { useEffect, useRef, useState, type DragEvent } from "react";
+import { useAssignGroup } from "@/data/session-groups";
+import {
+  DRAG_TYPE,
+  dragging,
+  dropOutcome,
+  setDragging,
+  type DraggedSession,
+  type DropTarget,
+} from "@/lib/sidebar/groupDrop";
+
+// A session row you can pick up. Whole-row drag; the row's own click and
+// menus are untouched, and touch keeps using Move to group.
+export function useRowDrag(dragged: DraggedSession, enabled: boolean) {
+  return {
+    draggable: enabled,
+    onDragStart: (e: DragEvent) => {
+      setDragging(dragged);
+      e.dataTransfer.effectAllowed = "move";
+      e.dataTransfer.setData(DRAG_TYPE, dragged.id);
+    },
+    onDragEnd: () => setDragging(null),
+  };
+}
+
+const EXPAND_AFTER_MS = 600;
+
+// Where a dragged session can land. A group passes itself as the target; the
+// list around the groups passes null, which takes the session out of its group.
+export function useDropZone(
+  target: DropTarget | null,
+  // A folded group opens when a valid drag rests on it.
+  onRest?: () => void
+) {
+  const assign = useAssignGroup();
+  const [over, setOver] = useState(false);
+  const timer = useRef<ReturnType<typeof setTimeout>>(undefined);
+  const stopRest = () => clearTimeout(timer.current);
+  useEffect(() => stopRest, []);
+
+  const outcome = () => {
+    const d = dragging();
+    return d ? { d, out: dropOutcome(d, target) } : null;
+  };
+  const leave = () => {
+    stopRest();
+    setOver(false);
+  };
+
+  return {
+    over,
+    props: {
+      onDragOver: (e: DragEvent) => {
+        const o = outcome();
+        if (!o?.out) return;
+        e.preventDefault();
+        e.stopPropagation();
+        e.dataTransfer.dropEffect = "move";
+        if (target) {
+          setOver(true);
+          if (onRest && !timer.current)
+            timer.current = setTimeout(onRest, EXPAND_AFTER_MS);
+        }
+      },
+      onDragLeave: (e: DragEvent) => {
+        if (!e.currentTarget.contains(e.relatedTarget as Node | null)) {
+          leave();
+          timer.current = undefined;
+        }
+      },
+      onDrop: (e: DragEvent) => {
+        const o = outcome();
+        leave();
+        timer.current = undefined;
+        if (!o?.out) return;
+        e.preventDefault();
+        e.stopPropagation();
+        setDragging(null);
+        assign.mutate({ ids: [o.d.id], groupId: o.out.groupId });
+      },
+    },
+  };
+}

package/components/Updates/UpdateActions.tsx

@@ -50,6 +50,12 @@ export function UpdateActions({ view }: { view: UpdateView }) {
         Cancel
       </Button>
     );
+  if (view.canUpdate.code === "no_restart")
+    return (
+      <Button size="sm" className="min-h-11 md:min-h-0" disabled>
+        Update now
+      </Button>
+    );
   if (!view.canUpdate.ok) return null;
 
   const start = (when: "now" | "idle") => {

package/components/Updates/UpdateBanner.test.ts

@@ -50,6 +50,7 @@ const make = (over: Partial<UpdateView> = {}): UpdateView => ({
   checkError: null,
   bannerEnabled: true,
   bannerLocked: false,
+  canRestart: true,
   canUpdate: { ok: true },
   run: null,
   pending: null,

package/data/exports/queries.ts

@@ -49,3 +49,14 @@ export async function fetchExport(
     name: exportFileName(title, sel ? rangeSlug(sel) : "all", req.format),
   };
 }
+
+/** One turn as Markdown (secrets masked), and its last agent message. */
+export async function fetchTurnCopy(
+  sessionId: string,
+  startId: string
+): Promise<{ full: string; response: string }> {
+  const res = await post(`/api/sessions/${sessionId}/export/turn`, {
+    startId,
+  });
+  return res.ok ? res.json() : failure(res);
+}

package/lib/agents/brief.ts

@@ -1,7 +1,7 @@
 // What every agent AgentOS starts is told about waiting; the note sent after
 // AgentOS stops a spinning background job repeats it (lib/health/spin.ts).
 export const WAIT_ADVICE =
-  "To wait for a long command, run it with run_in_background and end your turn; you're woken when it exits. Don't start a second job to poll for the first. Any wait loop must sleep on each pass and test a condition that can actually become true (pgrep for the exact process, a log line), never a fixed sleep.";
+  "To wait for a long command, run it with run_in_background and end your turn; you're woken when it exits. Don't start a second job to poll for the first. Any wait loop must sleep on each pass and test a condition that can actually become true (pgrep for the exact process, a log line), never a fixed sleep. Never wait for a port another process holds: `aos port` gives you a free one.";
 
 // What every agent AgentOS starts is told about the network it's on.
 export const BUS_BRIEF = `You are one of several coding agents running in AgentOS. Other sessions may be working on related projects at the same time, and you can talk to them with the \`aos\` command:

package/lib/claims/collectLocal.ts

@@ -7,6 +7,7 @@ import { git } from "../git-exec";
 import { repoKey } from "../git-remote";
 import { IN_FLIGHT } from "../tasks/queue-rows";
 import { expandHome } from "../tasks/session";
+import { isNoise } from "./overlap";
 import { MAX_FILES } from "./types";
 import {
   localLiveSessionIds,
@@ -47,7 +48,8 @@ export async function changedFiles(
     git(dir, ["ls-files", "--others", "--exclude-standard", "-z"], OPTS),
   ]);
   return [...new Set([...paths(committed), ...paths(untracked)])].filter(
-    (p) => !p.split("/").some((seg) => seg.endsWith(".aos-partial"))
+    (p) =>
+      !p.split("/").some((seg) => seg.endsWith(".aos-partial")) && !isNoise(p)
   );
 }
 

package/lib/claims/overlap.ts

@@ -7,8 +7,28 @@ import type { Claim, Overlap } from "./types";
 const NOISE =
   /(^|\/)(package-lock\.json|pnpm-lock\.yaml|yarn\.lock|Gemfile\.lock|Cargo\.lock|go\.sum|poetry\.lock|uv\.lock|composer\.lock|CHANGELOG[^/]*|__snapshots__\/.*|migrations\.generated\.ts)$/i;
 
-export const isNoise = (path: string) =>
-  NOISE.test(path) || /(^|\/)__snapshots__\//.test(path);
+// Build output, caches and OS files: directory segments (never name substrings).
+const NOISE_DIRS = new Set([
+  "__pycache__",
+  "node_modules",
+  ".next",
+  "dist",
+  "build",
+  "coverage",
+  ".pytest_cache",
+  ".mypy_cache",
+  ".ruff_cache",
+]);
+const NOISE_FILE = /(\.(pyc|pyo|tsbuildinfo)|^\.DS_Store)$/;
+
+export const isNoise = (path: string) => {
+  if (NOISE.test(path) || /(^|\/)__snapshots__\//.test(path)) return true;
+  const segs = path.split("/");
+  return (
+    segs.slice(0, -1).some((s) => NOISE_DIRS.has(s)) ||
+    NOISE_FILE.test(segs[segs.length - 1])
+  );
+};
 
 // A path this many claims touch is a shared index or router, not a signal.
 export const HUB_CLAIMS = 4;

package/lib/export/markdown.ts

@@ -25,7 +25,10 @@ const quote = (s: string) =>
     .map((l) => (l ? `> ${l}` : ">"))
     .join("\n");
 
-function itemMd(i: ExportItem): string {
+export const UNAVAILABLE = "[output unavailable]";
+export const UNAVAILABLE_RUNNING = "[output unavailable: tool still running]";
+
+export function itemMd(i: ExportItem): string {
   const t = clock(i.at);
   switch (i.kind) {
     case "user": {
@@ -59,6 +62,9 @@ function itemMd(i: ExportItem): string {
         );
       if (i.diff?.patch) parts.push(fenced(i.diff.patch, "diff"));
       if (i.output) parts.push(`Output:\n\n${fenced(i.output)}`);
+      else if (i.status === "running") parts.push(UNAVAILABLE_RUNNING);
+      else if (i.status === "stopped" || i.status === "error")
+        parts.push(UNAVAILABLE);
       return parts.join("\n\n");
     }
     case "command_output":

package/lib/export/turn.ts

@@ -0,0 +1,48 @@
+/**
+ * One turn as Markdown for the clipboard: the same model and serializer as a
+ * session export (build.ts, markdown.ts), redacted for secrets, cut to one turn.
+ */
+
+import type { ChatItem } from "../chat/events";
+import type { ShareContext } from "../share/redact";
+import { BadShare } from "../share/service";
+import { buildDoc, type BuildInput, type ExportTurn } from "./build";
+import { itemMd } from "./markdown";
+import { groupTurns } from "./turns";
+
+export interface TurnCopy {
+  /** Reasoning, tool calls and their output, errors and the answer, in order. */
+  full: string;
+  /** The turn's last agent message. */
+  response: string;
+}
+
+/** The turn body: every item after the message that began it. */
+export function turnMarkdown(turn: ExportTurn): TurnCopy {
+  // The first item is the message that began the turn: already on screen.
+  const body = turn.userId ? turn.items.slice(1) : turn.items;
+  const parts = body.map(itemMd);
+  if (turn.ended) parts.push(`*Turn ended early: ${turn.ended}*`);
+  if (turn.interrupted) parts.push("*Turn stopped before it finished*");
+  const last = [...turn.items].reverse().find((i) => i.kind === "assistant");
+  return { full: parts.join("\n\n"), response: last?.text ?? "" };
+}
+
+/** The turn that begins with message `startId`. 404 as BadShare. */
+export function copyTurn(
+  items: ChatItem[],
+  startId: string,
+  ctx: ShareContext,
+  meta: BuildInput["meta"]
+): TurnCopy {
+  const turn = groupTurns(items).find((t) => t.items[0]?.id === startId);
+  if (!turn) throw new BadShare("Turn not found", 404);
+  const doc = buildDoc({
+    items: turn.items,
+    meta,
+    mode: "full",
+    redact: "secrets",
+    ctx,
+  });
+  return turnMarkdown(doc.turns[0]);
+}

package/lib/health/config.ts

@@ -8,6 +8,7 @@ export const HEALTH_DEFAULTS = {
   loadRedMinutes: 10,
   queueHeldMinutes: 60,
   bgQuietMinutes: 20,
+  portWaitMinutes: 10,
   pieceDupOverlap: 0.4,
   restartsMax: 2,
   restartsWindowMinutes: 60,
@@ -33,6 +34,7 @@ export const HEALTH_LABELS: Record<HealthKey, string> = {
   loadRedMinutes: "Machine load red for (minutes)",
   queueHeldMinutes: "Queued task held for (minutes)",
   bgQuietMinutes: "Background job quiet for (minutes)",
+  portWaitMinutes: "Waiting on a port someone else holds for (minutes)",
   pieceDupOverlap: "Plan piece matches merged work (0 to 1 overlap)",
   restartsMax: "Server restarts allowed per window",
   restartsWindowMinutes: "Restart window (minutes)",

package/lib/health/env/classes.ts

@@ -11,6 +11,19 @@ const USE_ENV =
   "run it through the repo's own environment (`uv run …` when it has a pyproject.toml or uv.lock, else its .venv/bin/python), not a bare `python3`";
 
 export const ENV_CLASSES: readonly EnvClass[] = [
+  {
+    id: "port-in-use",
+    label: "Port taken by another process",
+    scope: "shell",
+    match: [
+      /\bEADDRINUSE\b/,
+      /^(?:\S+Error: )?(?:\[Errno \d+\] )?Address already in use\b/i,
+      /^(?:Error: )?Port \d+ is already in use\b/,
+      /^Something is already running on port \d+/,
+      /\bport is already allocated\b/,
+    ],
+    fix: "A port this command needs is taken by another process on this machine. Don't wait for it and don't stop it: run `aos port <that port>` to see who holds it and get a free one, then start on that one (pass it with --port or PORT=). If you need that exact port, tell the orchestrator.",
+  },
   {
     id: "python-version",
     label: "Python too old for the code",
@@ -116,4 +129,4 @@ export const SHELL_TOOLS = new Set([
 // Commands that show text somebody else wrote: an error in their output is
 // in the data, not something this run hit.
 export const READERS =
-  /^(?:grep|egrep|rg|ag|cat|head|tail|less|more|sed\s+-n|awk|jq|sqlite3|journalctl|echo|printf|aos\s+(?:history|inbox)|sm\s+logs|gh\s+run\s+view|git\s+(?:log|show|diff|grep))\b/;
+  /^(?:grep|egrep|rg|ag|cat|head|tail|less|more|ls|wc|sed\s+-n|awk|jq|sqlite3|journalctl|echo|printf|aos\s+(?:history|inbox)|sm\s+logs|gh\s+run\s+view|git\s+(?:log|show|diff|grep))\b/;

package/lib/health/port-wait-tick.ts

@@ -0,0 +1,222 @@
+/**
+ * The I/O half of port-wait (port-wait.ts decides): once a minute, find the
+ * sessions' shell loops that have waited on a port for long enough, ask who
+ * holds that port, and when it's someone else tell the agent and its
+ * orchestrator once per holder. Nothing is stopped: a sleeping loop costs
+ * nothing, and the agent ends its own job. Each machine judges its own
+ * sessions, since ports only meet inside one machine's network.
+ */
+
+import { execFile } from "child_process";
+import { sendMessage } from "../bus";
+import { db } from "../db";
+import { readSnapshot } from "../load/usage";
+import { queueEventOnce } from "../orchestrator/events";
+import { untrusted } from "../orchestrator/untrusted";
+import {
+  describeHolder,
+  judgePort,
+  listListeners,
+  localPortRows,
+  sessionPorts,
+  type Holder,
+} from "../ports";
+import { cwdsOf } from "../ports/listListeners";
+import type { HealthConfig } from "./config";
+import {
+  findPortWaits,
+  parsePsArgs,
+  portWaitLine,
+  portWaitNote,
+  waitedPorts,
+  type ArgsProc,
+  type WaitSession,
+} from "./port-wait";
+import { close, recordTrips } from "./store";
+import { MIN, type Trip } from "./types";
+
+export interface PortWaitDeps {
+  procs: () => Promise<ArgsProc[] | null>;
+  panes: () => Promise<{ tmux: string; pid: number }[]>;
+  cwds: (pids: number[]) => Promise<Map<number, string>>;
+  listeners: typeof listListeners;
+  portRows: typeof localPortRows;
+  sessions: () => WaitSession[];
+  tell: (sessionId: string, body: string) => Promise<void>;
+  event: (
+    workspaceId: string,
+    key: string,
+    subject: string,
+    line: string,
+    now: number
+  ) => void;
+  record: (trip: Trip, now: number) => void;
+}
+
+const readArgs = (): Promise<ArgsProc[] | null> =>
+  new Promise((resolve) =>
+    execFile(
+      "ps",
+      ["-Ao", "pid=,ppid=,etime=,args="],
+      { timeout: 5000, maxBuffer: 16 << 20 },
+      (err, out) => {
+        const rows = err ? [] : parsePsArgs(out);
+        resolve(rows.length ? rows : null);
+      }
+    )
+  );
+
+function localSessions(): WaitSession[] {
+  return (
+    db
+      .prepare(
+        `SELECT s.id, s.name, p.workspace_id, s.tmux_name, s.worktree_path
+         FROM sessions s LEFT JOIN projects p ON p.id = s.project_id
+         WHERE s.archived_at IS NULL AND (s.host_id IS NULL OR s.host_id = 'local')`
+      )
+      .all() as {
+      id: string;
+      name: string;
+      workspace_id: string | null;
+      tmux_name: string | null;
+      worktree_path: string | null;
+    }[]
+  ).map((r) => ({
+    id: r.id,
+    name: r.name,
+    workspaceId: r.workspace_id,
+    tmuxName: r.tmux_name,
+    worktree: r.worktree_path,
+  }));
+}
+
+export const realPortWait: PortWaitDeps = {
+  procs: readArgs,
+  panes: async () => (await readSnapshot()).panes,
+  cwds: cwdsOf,
+  listeners: listListeners,
+  portRows: localPortRows,
+  sessions: localSessions,
+  tell: async (sessionId, body) => {
+    await sendMessage({
+      fromId: null,
+      to: sessionId,
+      body,
+      fromLabel: "AgentOS health",
+      origin: { kind: "system", label: "Health", body },
+    });
+  },
+  event: (ws, key, subject, line, now) => {
+    queueEventOnce(ws, key, subject, line, now);
+  },
+  record: (trip, now) => {
+    const { opened } = recordTrips([trip], [], now);
+    // History only: the agent and orchestrator are told directly.
+    for (const row of opened) close(row.id, "told", now);
+  },
+};
+
+const holderKey = (h: Holder) =>
+  h.kind === "session"
+    ? `s:${h.sessionId}`
+    : h.kind === "dev-server"
+      ? `d:${h.id}`
+      : `${h.kind}:${h.pid}`;
+
+// session:port -> the holder it was told about. A wait that ends, or a new
+// holder, re-arms it.
+const told = new Map<string, string>();
+let running = false;
+
+export function resetPortWait(): void {
+  told.clear();
+  running = false;
+}
+
+export async function portWaitTick(
+  now: number,
+  c: HealthConfig,
+  deps: PortWaitDeps = realPortWait
+): Promise<void> {
+  const minMs = c.portWaitMinutes * MIN;
+  if (!minMs || running) return;
+  running = true;
+  try {
+    const procs = await deps.procs();
+    if (!procs) return;
+    const old = procs.filter(
+      (p) => p.ageMs >= minMs && waitedPorts(p.args).length
+    );
+    if (!old.length) {
+      told.clear();
+      return;
+    }
+    const [panes, cwds] = await Promise.all([
+      deps.panes(),
+      deps.cwds(old.map((p) => p.pid)),
+    ]);
+    const waits = findPortWaits(procs, deps.sessions(), panes, cwds, minMs);
+    const live = new Set(waits.map((w) => `${w.sessionId}:${w.port}`));
+    for (const k of told.keys()) if (!live.has(k)) told.delete(k);
+    if (!waits.length) return;
+    const listeners = await deps.listeners();
+    if (!listeners) return;
+    const { sessions, devServers } = deps.portRows();
+    for (const w of waits) {
+      const check = judgePort(
+        w.sessionId,
+        null,
+        w.port,
+        listeners,
+        sessions,
+        devServers
+      );
+      if (!check.holder || check.mine) continue;
+      const key = `${w.sessionId}:${w.port}`;
+      const who = holderKey(check.holder);
+      if (told.get(key) === who) continue;
+      told.set(key, who);
+      const holder = describeHolder(check.holder);
+      const line = portWaitLine(w, holder);
+      try {
+        deps.record(
+          {
+            check: "port-wait",
+            subject: key,
+            severity: "warn",
+            line,
+            detail: {
+              sessionId: w.sessionId,
+              port: w.port,
+              pid: w.pid,
+              holder: check.holder,
+            },
+            workspaceId: w.workspaceId,
+          },
+          now
+        );
+      } catch (error) {
+        console.error("[health] port-wait record:", error);
+      }
+      if (w.workspaceId)
+        deps.event(
+          w.workspaceId,
+          `port-wait:${key}:${who}`,
+          w.sessionId,
+          // Session names and commands are agents' own text.
+          `Health (tasks): ${untrusted("health detector", line)}`,
+          now
+        );
+      try {
+        await deps.tell(
+          w.sessionId,
+          portWaitNote(w, holder, sessionPorts(w.sessionId))
+        );
+      } catch (error) {
+        console.error("[health] port-wait note:", error);
+      }
+    }
+  } finally {
+    running = false;
+  }
+}

package/lib/health/port-wait.ts

@@ -0,0 +1,160 @@
+/**
+ * port-wait, the deciding half (port-wait-tick.ts does the I/O): a shell
+ * loop that waits on a port someone else holds can't end, since that holder
+ * won't free it for the agent. Sleeping loops use no CPU, so bg-spin never
+ * sees them; this names the holder and the way out instead.
+ */
+
+import { claimTrees } from "../load/usage";
+import { MIN } from "./types";
+
+export const PORT_WAIT_MIN_MS = 10 * MIN;
+
+const LOOP =
+  /\b(?:until|while)\b[\s\S]*?\b(?:curl|wget|nc|lsof|ss|netstat|http)\b|\bwait-on\b|\bwait-port\b/;
+const PORT_REFS = [
+  /(?:localhost|127\.0\.0\.1|0\.0\.0\.0|\[::1\]):(\d{2,5})\b/g,
+  /\btcp:(\d{2,5})\b/g,
+  /\s-i\s*:(\d{2,5})\b/g,
+  /\b[sd]port\s*=\s*:(\d{2,5})\b/g,
+  /\bnc\s+(?:-\w+\s+)*\S+\s+(\d{2,5})\b/g,
+];
+
+// The ports a command waits on, when it is a wait loop at all.
+export function waitedPorts(args: string): number[] {
+  if (!LOOP.test(args)) return [];
+  const ports = new Set<number>();
+  for (const re of PORT_REFS)
+    for (const m of args.matchAll(re)) {
+      const p = Number(m[1]);
+      if (p > 0 && p <= 65535) ports.add(p);
+    }
+  return [...ports];
+}
+
+// ps's etime, `[[dd-]hh:]mm:ss`, in seconds.
+export function parseEtime(s: string): number | null {
+  const m = /^(?:(\d+)-)?(?:(\d+):)?(\d+):(\d+)$/.exec(s.trim());
+  if (!m) return null;
+  const [, d, h, mm, ss] = m;
+  return (
+    ((Number(d ?? 0) * 24 + Number(h ?? 0)) * 60 + Number(mm)) * 60 + Number(ss)
+  );
+}
+
+export interface ArgsProc {
+  pid: number;
+  ppid: number;
+  ageMs: number;
+  args: string;
+}
+
+// `ps -Ao pid=,ppid=,etime=,args=`: args is last and holds spaces.
+export function parsePsArgs(out: string): ArgsProc[] {
+  const rows: ArgsProc[] = [];
+  for (const line of out.split("\n")) {
+    const m = /^\s*(\d+)\s+(\d+)\s+(\S+)\s+(.*)$/.exec(line);
+    if (!m) continue;
+    const age = parseEtime(m[3]);
+    if (age === null) continue;
+    rows.push({
+      pid: Number(m[1]),
+      ppid: Number(m[2]),
+      ageMs: age * 1000,
+      args: m[4],
+    });
+  }
+  return rows;
+}
+
+export interface WaitSession {
+  id: string;
+  name: string;
+  workspaceId: string | null;
+  tmuxName: string | null;
+  worktree: string | null;
+}
+
+export interface PortWait {
+  sessionId: string;
+  sessionName: string;
+  workspaceId: string | null;
+  pid: number;
+  port: number;
+  args: string;
+  waitedMs: number;
+}
+
+const inside = (cwd: string, dir: string) =>
+  cwd === dir || cwd.startsWith(`${dir.replace(/\/$/, "")}/`);
+
+/**
+ * Each session's waits on a port for at least `minMs`, one per session and
+ * port (a loop's wrapper shells are folded into its oldest). A process is
+ * the session's when it runs in its worktree, or under its tmux pane.
+ */
+export function findPortWaits(
+  procs: ArgsProc[],
+  sessions: WaitSession[],
+  panes: { tmux: string; pid: number }[],
+  cwds: Map<number, string>,
+  minMs: number
+): PortWait[] {
+  const byTmux = new Map(
+    sessions.filter((s) => s.tmuxName).map((s) => [s.tmuxName!, s])
+  );
+  const roots = panes
+    .filter((p) => byTmux.has(p.tmux))
+    .map((p) => ({ key: byTmux.get(p.tmux)!.id, pid: p.pid }));
+  const owner = claimTrees(
+    procs.map((p) => ({ pid: p.pid, ppid: p.ppid, pcpu: 0, rss: 0 })),
+    roots
+  );
+  const out = new Map<string, PortWait>();
+  for (const p of procs) {
+    if (p.ageMs < minMs) continue;
+    const ports = waitedPorts(p.args);
+    if (!ports.length) continue;
+    const cwd = cwds.get(p.pid);
+    const s =
+      (cwd && sessions.find((x) => x.worktree && inside(cwd, x.worktree))) ||
+      sessions.find((x) => x.id === owner.get(p.pid));
+    if (!s) continue;
+    for (const port of ports) {
+      const key = `${s.id}:${port}`;
+      const had = out.get(key);
+      if (had && had.waitedMs >= p.ageMs) continue;
+      out.set(key, {
+        sessionId: s.id,
+        sessionName: s.name,
+        workspaceId: s.workspaceId,
+        pid: p.pid,
+        port,
+        args: p.args,
+        waitedMs: p.ageMs,
+      });
+    }
+  }
+  return [...out.values()];
+}
+
+const short = (args: string) =>
+  args.length > 120 ? `${args.slice(0, 117)}...` : args;
+
+export function portWaitNote(
+  w: PortWait,
+  holder: string,
+  own: Record<string, number> | null
+): string {
+  const mins = Math.round(w.waitedMs / MIN);
+  const mine =
+    own && Object.keys(own).length
+      ? ` Your ports are ${Object.entries(own)
+          .map(([n, p]) => `${n}=${p}`)
+          .join(", ")}.`
+      : "";
+  return `You've waited ${mins} min for port ${w.port} (pid ${w.pid}: \`${short(w.args)}\`). It's held by ${holder}, which isn't yours and won't free it for you, so that wait can't end. Stop it (\`kill ${w.pid}\`, your own job), don't stop the holder, and run \`aos port ${w.port}\` for a free port of your own to start on.${mine} If you need ${w.port} itself, tell the orchestrator.`;
+}
+
+export const portWaitLine = (w: PortWait, holder: string) =>
+  `${w.sessionName} has waited ${Math.round(w.waitedMs / MIN)} min for port ${w.port}, held by ${holder}. It was told to move to its own port.`;