@saadnvd1/agent-os 0.3.810 → 0.3.815

package/README.md

@@ -55,16 +55,17 @@ You need Node.js 22+, git, tmux, and at least one agent CLI (the installer offer
 ```bash
 npm install -g @saadnvd1/agent-os
 agent-os install   # checks for tmux and ripgrep, installs what's missing, builds the app
-agent-os start     # runs in the background on http://localhost:3011
+agent-os setup     # keeps it running, chooses how your phone reaches it, adds the phone
 ```
 
 Without Node.js, the install script sets up everything:
 
 ```bash
 curl -fsSL https://raw.githubusercontent.com/saadnvd1/agent-os/main/scripts/install.sh | bash
-agent-os start
 ```
 
+It ends by offering `agent-os setup`. If another device can't reach the machine later, `agent-os check` names the cause and the fix ([guide](docs/guides/reachability.md)).
+
 Then open AgentOS, add a project from ⌘K, and press ⌥N. The [install guide](docs/guides/install.md) covers Windows (WSL2), the supported agents, first run and the `agent-os` commands. To use it from your phone, see the [phone guide](docs/guides/phone.md).
 
 ## Connect

package/app/api/reach/probe/route.test.ts

@@ -0,0 +1,22 @@
+import { describe, expect, it } from "vitest";
+import { GET } from "./route";
+
+// Public before pairing: it may only ever say "AgentOS, this boot".
+describe("GET /api/reach/probe", () => {
+  it("answers the same two fields to everyone, all boot long, uncached", async () => {
+    const a = GET();
+    const b = GET();
+    const body = await a.json();
+    expect(Object.keys(body).sort()).toEqual(["boot", "ok"]);
+    expect(body).toEqual({
+      ok: true,
+      boot: expect.stringMatching(/^[0-9a-f]{16}$/),
+    });
+    expect(await b.json()).toEqual(body);
+    expect(a.headers.get("cache-control")).toBe("no-store");
+  });
+
+  it("takes no input", () => {
+    expect(GET.length).toBe(0);
+  });
+});

package/app/api/reach/probe/route.ts

@@ -0,0 +1,12 @@
+import { NextResponse } from "next/server";
+import { bootId } from "@/lib/reach/probeConnect";
+
+// GET /api/reach/probe - public: the same answer for anyone, all boot long.
+// This machine fetches it through its own Connect address to prove the
+// answer came from this process, not a cache or another AgentOS.
+export function GET() {
+  return NextResponse.json(
+    { ok: true, boot: bootId() },
+    { headers: { "Cache-Control": "no-store" } }
+  );
+}

package/app/api/reach/route.ts

@@ -0,0 +1,30 @@
+import { NextRequest, NextResponse } from "next/server";
+import { checkReach } from "@/lib/reach/checkReach";
+import { classifyReach } from "@/lib/reach/classify";
+import { demoMode } from "@/lib/security/demo";
+import type { ReachRoute } from "@/lib/reach/types";
+
+const ROUTES = new Set<string>(["connect", "tailscale", "lan"]);
+
+// GET /api/reach[?fresh][&want=lan,connect] - can other devices reach this
+// machine, and if not, why. `want` adds routes the caller means to use.
+export async function GET(request: NextRequest) {
+  if (demoMode()) return NextResponse.json(demoReach());
+  const params = request.nextUrl.searchParams;
+  const want = (params.get("want") ?? "")
+    .split(",")
+    .filter((r): r is ReachRoute => ROUTES.has(r));
+  return NextResponse.json(await checkReach(params.has("fresh"), want));
+}
+
+// Nothing about the machine a demo runs on.
+function demoReach() {
+  return classifyReach({
+    now: Date.now(),
+    port: 3011,
+    lan: { on: false, addresses: [] },
+    firewall: "unknown",
+    tailscale: { state: "missing" },
+    connect: { state: "off", linked: false, enabled: false },
+  });
+}

package/app/api/sessions/list-size.test.ts

@@ -0,0 +1,77 @@
+import { randomUUID } from "crypto";
+import { beforeEach, describe, expect, it } from "vitest";
+
+const { db, insertSessionRow } = await import("@/lib/db");
+const { GET } = await import("./route");
+
+type Row = Record<string, unknown> & { id: string };
+
+function seed(extra: Record<string, unknown> = {}): string {
+  const id = randomUUID();
+  insertSessionRow(db, {
+    id,
+    name: "n",
+    tmux_name: `claude-${id}`,
+    working_directory: "/tmp",
+    ...extra,
+  });
+  return id;
+}
+
+const list = async (query = "") => {
+  const res = await GET({
+    nextUrl: new URL(`http://x/api/sessions${query}`),
+  } as never);
+  return (await res.json()).sessions as Row[];
+};
+
+beforeEach(() => {
+  db.prepare(`DELETE FROM sessions`).run();
+});
+
+describe("GET /api/sessions payload", () => {
+  it("never carries the full prompt, the chat context or the orchestrator token", async () => {
+    const id = seed({
+      task_status: "running",
+      task_prompt: "x".repeat(5000),
+      chat_context: "ctx",
+      orch_token: "secret-token",
+    });
+    const row = (await list()).find((r) => r.id === id)!;
+    // Installed phone builds read !!task_prompt, so a short prefix stays.
+    expect(row.task_prompt).toBe("x".repeat(80));
+    expect(row).not.toHaveProperty("chat_context");
+    expect(row).not.toHaveProperty("orch_token");
+    expect(row.has_prompt).toBe(1);
+  });
+
+  it("says has_prompt 0 for a plain session", async () => {
+    const id = seed();
+    expect((await list()).find((r) => r.id === id)!.has_prompt).toBe(0);
+  });
+
+  it("leaves null fields out", async () => {
+    const id = seed();
+    const row = (await list()).find((r) => r.id === id)!;
+    expect(Object.values(row)).not.toContain(null);
+    expect(row).not.toHaveProperty("pr_url");
+  });
+
+  it("lists the 100 most recent merged tasks, all with ?done=all", async () => {
+    for (let i = 0; i < 103; i++) {
+      const day = String(i + 1).padStart(3, "0");
+      seed({
+        task_status: "merged",
+        merged_at: `2026-01-01 00:00:${i % 60}`.replace(/:(\d)$/, ":0$1"),
+        updated_at: `2026-02-01 00:00:00`,
+        name: `done-${day}`,
+      });
+    }
+    const live = seed({ task_status: "running" });
+    const capped = await list();
+    expect(capped.filter((r) => r.task_status === "merged")).toHaveLength(100);
+    expect(capped.map((r) => r.id)).toContain(live);
+    const all = await list("?done=all");
+    expect(all.filter((r) => r.task_status === "merged")).toHaveLength(103);
+  });
+});

package/app/api/sessions/route.ts

@@ -10,9 +10,14 @@ import { ModelUnavailableError } from "@/lib/models/agent-binding";
 import { namesLine, waitBadges } from "@/lib/bus/waits/store";
 import { claimsSnapshot } from "@/lib/claims";
 import { isProjectRef } from "@/lib/tasks/project-ref";
+import { omitNulls } from "@/lib/sessions/omit-null";
+
+// The sidebar's Done shelf lists this many finished tasks; ?done=all lists
+// every one.
+const DONE_LISTED = 100;
 
 // GET /api/sessions - List the sidebar's sessions and the user's groups
-export async function GET() {
+export async function GET(request?: NextRequest) {
   try {
     const db = getDb();
     // Merged tasks are listed (the sidebar files them under Done). Dropped
@@ -20,12 +25,18 @@ export async function GET() {
     // and archived sessions in the Archived view: none is in the sidebar.
     const badges = waitBadges();
     const claims = claimsSnapshot();
-    const sessions = (queries.getSidebarSessions(db).all() as Session[]).map(
-      (s) => {
-        const b = badges.get(s.id);
-        const overlap = claims.bySession.get(s.id);
-        const row = overlap ? { ...s, overlap } : s;
-        return b
+    const all = request?.nextUrl.searchParams.get("done") === "all";
+    const rows = (
+      all
+        ? queries.getSidebarSessions(db).all()
+        : queries.getSidebarSessionsCapped(db, DONE_LISTED).all()
+    ) as Session[];
+    const sessions = rows.map((s) => {
+      const b = badges.get(s.id);
+      const overlap = claims.bySession.get(s.id);
+      const row = overlap ? { ...s, overlap } : s;
+      return omitNulls(
+        b
           ? {
               ...row,
               waiting_on: b.on.length
@@ -35,9 +46,9 @@ export async function GET() {
                 ? namesLine(b.by.map((w) => w.name))
                 : null,
             }
-          : row;
-      }
-    );
+          : row
+      );
+    });
     return NextResponse.json({
       sessions,
       sessionGroups: listGroups(),

package/app/api/tasks/list-size.test.ts

@@ -0,0 +1,50 @@
+import { randomUUID } from "crypto";
+import { describe, expect, it } from "vitest";
+
+const { db, insertSessionRow } = await import("@/lib/db");
+const { GET } = await import("./route");
+
+describe("GET /api/tasks payload", () => {
+  it("lists hasPrompt, not the prompt text, and leaves null fields out", async () => {
+    const id = randomUUID();
+    insertSessionRow(db, {
+      id,
+      name: "t",
+      tmux_name: `claude-${id}`,
+      working_directory: "/tmp",
+      task_status: "running",
+      task_prompt: "p".repeat(5000),
+    });
+    const { tasks } = await (await GET()).json();
+    const t = tasks.find((x: { id: string }) => x.id === id);
+    expect(t.hasPrompt).toBe(true);
+    expect(t).not.toHaveProperty("prompt");
+    expect(JSON.stringify(t)).not.toContain("ppppp");
+    expect(Object.values(t)).not.toContain(null);
+  });
+});
+
+describe("taskSessions with a merged limit", () => {
+  it("keeps the most recently merged ones and every unmerged one", async () => {
+    const { taskSessions } = await import("@/lib/tasks/session");
+    const add = (status: string, merged_at: string | null) => {
+      const id = randomUUID();
+      insertSessionRow(db, {
+        id,
+        name: "t",
+        tmux_name: `claude-${id}`,
+        working_directory: "/tmp",
+        task_status: status,
+        merged_at,
+      });
+      return id;
+    };
+    const oldest = add("merged", "2020-01-01 00:00:00");
+    const newer = add("merged", "2020-01-03 00:00:00");
+    const newest = add("merged", "2020-01-04 00:00:00");
+    const running = add("running", null);
+    const ids = taskSessions(false, 2).map((s) => s.id);
+    expect(ids).toEqual(expect.arrayContaining([newer, newest, running]));
+    expect(ids).not.toContain(oldest);
+  });
+});

package/app/api/tasks/route.ts

@@ -1,6 +1,6 @@
 import { parseOverride } from "@/lib/models/resolve";
 import { NextRequest, NextResponse } from "next/server";
-import { createTask, listTasks, movedTasks } from "@/lib/tasks";
+import { createTask, listTasks, movedTasks, type TaskView } from "@/lib/tasks";
 import { stampPriority, startOrQueue } from "@/lib/tasks/queue";
 import { isPriority } from "@/lib/tasks/schedule-types";
 import { TASK_CAPABILITIES } from "@/lib/tasks/contract/types";
@@ -13,12 +13,29 @@ import {
 } from "@/lib/tasks/move-bundle";
 import { startView } from "@/lib/sessions/launch";
 import { isValidAgentType } from "@/lib/providers";
+import { omitNulls } from "@/lib/sessions/omit-null";
 import { isAgentModelName } from "@/lib/providers/registry";
 
+// The most recent merged tasks the list holds; ?done=all lists every one.
+const MERGED_LISTED = 100;
+
+// A task as the list shows it: no prompt text (a mirrored one from a machine
+// that still sends it included) and no null fields.
+function listed(task: TaskView) {
+  const { prompt: _prompt, ...rest } = task;
+  return omitNulls(rest);
+}
+
 // moved and capabilities are for another machine that mirrors these tasks.
-export async function GET() {
+export async function GET(request?: NextRequest) {
   return NextResponse.json({
-    tasks: await listTasks(),
+    tasks: (
+      await listTasks(
+        request?.nextUrl.searchParams.get("done") === "all"
+          ? undefined
+          : MERGED_LISTED
+      )
+    ).map(listed),
     moved: movedTasks(),
     capabilities: TASK_CAPABILITIES,
   });

package/components/Chat/ViewSwitch.tsx

@@ -1,6 +1,7 @@
 "use client";
 
 import { MessageSquare, SquareTerminal } from "lucide-react";
+import { hasPrompt } from "@/lib/sessions/has-prompt";
 import type { Session } from "@/lib/db";
 import { supportsChat } from "@/lib/chat/capabilities";
 import { viewSwitchActions } from "@/stores/viewSwitch";
@@ -15,7 +16,7 @@ export function ViewSwitch({
   if (!session || !supportsChat(session.agent_type)) return null;
   if (session.host_id && session.host_id !== "local") return null;
   // A task's agent runs in its terminal with its brief; chat would end it.
-  if (session.task_prompt) return null;
+  if (hasPrompt(session)) return null;
   const options = [
     { view: "chat" as const, icon: MessageSquare, label: "Chat" },
     { view: "terminal" as const, icon: SquareTerminal, label: "Terminal" },

package/components/Devices/NetworkSection.tsx

@@ -4,6 +4,7 @@ import { SettingToggle as Toggle } from "@/components/Settings/SettingToggle";
 import { useNetworkQuery, useUpdateNetwork } from "@/data/devices";
 import { TailscaleCard } from "./TailscaleCard";
 import { ConnectCard } from "./ConnectCard";
+import { ReachRow } from "@/components/Reach/ReachRow";
 
 export function NetworkSection({
   open,
@@ -22,6 +23,7 @@ export function NetworkSection({
 
   return (
     <div className="space-y-2">
+      <ReachRow enabled={open} />
       <ConnectCard
         connect={data.connect}
         canManage={canManage}

package/components/Pane/index.tsx

@@ -1,5 +1,6 @@
 "use client";
 
+import { hasPrompt } from "@/lib/sessions/has-prompt";
 import { useTaskLogQuery } from "@/data/session-logs";
 import { SetupCard } from "@/components/Chat/SetupCard";
 import { SignInCard } from "@/components/Terminal/SignInCard";
@@ -217,10 +218,11 @@ export const Pane = memo(function Pane({
 
   // A merged task keeps the log AgentOS wrote of it.
   const merged =
-    !!session?.task_prompt &&
+    !!session &&
+    hasPrompt(session) &&
     (session.task_status === "merged" || session.pr_status === "merged");
   const hasLog = !!useTaskLogQuery(session?.id, merged).data;
-  const hasReport = !!session?.task_prompt;
+  const hasReport = !!session && hasPrompt(session);
 
   // Get current project and its repositories
   const currentProject = useMemo(() => {

package/components/Reach/ReachRow.tsx

@@ -0,0 +1,137 @@
+"use client";
+
+import { Loader2, RefreshCw } from "lucide-react";
+import { Button } from "@/components/ui/button";
+import { StatusPill } from "@/components/ui/status-pill";
+import { CopyButton } from "@/components/Chat/CopyButton";
+import { useReachQuery, useRecheckReach } from "@/data/reach";
+import type { ReachFinding, ReachReport, ReachStatus } from "@/lib/reach/types";
+import { cn } from "@/lib/utils";
+
+const TONE: Record<ReachStatus, "green" | "amber" | "red"> = {
+  ok: "green",
+  warn: "amber",
+  fail: "red",
+};
+
+// Amber has three stories: only retrying, one way in working, or a warning.
+function pillLabel(report: ReachReport, problems: ReachFinding[]): string {
+  if (report.status === "ok") return "Reachable";
+  if (report.status === "fail") return "Not reachable";
+  if (problems.every((f) => f.needs === "nothing")) return "Reconnecting";
+  return report.url ? "Partly reachable" : "Needs a look";
+}
+
+// A fix is a command when it starts with one; otherwise it's plain advice.
+const isCommand = (fix: string) => /^(agent-os|sudo)( |$)/.test(fix);
+
+function Problem({ f }: { f: ReachFinding }) {
+  return (
+    <li className="flex flex-col gap-1">
+      <p className="text-sm font-medium">{f.title}</p>
+      {f.needs === "nothing" ? (
+        <p className="text-muted-foreground flex items-center gap-1.5 text-xs">
+          <Loader2 className="size-3 animate-spin" />
+          Retrying on its own, nothing to do
+        </p>
+      ) : (
+        <>
+          {f.fix &&
+            (isCommand(f.fix) ? (
+              <code className="bg-background block rounded px-2 py-1 text-xs break-all">
+                {f.fix}
+              </code>
+            ) : (
+              <p className="text-muted-foreground text-xs break-words">
+                {f.fix}
+              </p>
+            ))}
+          {f.guide && (
+            <a
+              href={f.guide}
+              target="_blank"
+              rel="noopener noreferrer"
+              className="text-muted-foreground hover:text-foreground flex min-h-11 w-fit items-center text-xs underline underline-offset-2 sm:min-h-6"
+            >
+              How to fix
+            </a>
+          )}
+        </>
+      )}
+    </li>
+  );
+}
+
+/** Whether other devices can reach this machine, and the fix when they can't. */
+export function ReachRow({
+  enabled = true,
+  className,
+}: {
+  enabled?: boolean;
+  className?: string;
+}) {
+  const { data, isPending, isError } = useReachQuery(enabled);
+  const recheck = useRecheckReach();
+  if (isPending)
+    return (
+      <div
+        className={cn("bg-muted/40 h-16 animate-pulse rounded-lg", className)}
+      />
+    );
+  const problems = data?.findings.filter((f) => f.status !== "ok") ?? [];
+  const pill = data && {
+    tone: TONE[data.status],
+    label: pillLabel(data, problems),
+  };
+  return (
+    <div
+      className={cn(
+        "bg-muted/40 flex flex-col gap-2 rounded-lg px-3 py-2.5",
+        className
+      )}
+    >
+      <div className="flex min-h-11 items-center gap-2 sm:min-h-0">
+        <p className="min-w-0 flex-1 text-sm font-medium">
+          Reachable from other devices
+        </p>
+        {pill && (
+          <StatusPill tone={pill.tone} className="shrink-0 whitespace-nowrap">
+            {pill.label}
+          </StatusPill>
+        )}
+      </div>
+      {isError && (
+        <p className="text-destructive text-xs">Couldn&apos;t run the check.</p>
+      )}
+      {data?.url && (
+        <div className="flex min-w-0 items-center gap-1">
+          <span className="text-foreground min-w-0 flex-1 truncate font-mono text-xs">
+            {data.url}
+          </span>
+          <CopyButton
+            text={data.url}
+            label="Copy link"
+            className="h-11 w-11 shrink-0 md:h-7 md:w-7"
+          />
+        </div>
+      )}
+      {problems.length > 0 && (
+        <ul className="flex flex-col gap-3">
+          {problems.map((f, i) => (
+            <Problem key={`${f.route ?? ""}-${f.cause ?? i}`} f={f} />
+          ))}
+        </ul>
+      )}
+      <Button
+        size="sm"
+        variant="ghost"
+        className="h-11 self-end sm:h-8"
+        disabled={recheck.isPending}
+        onClick={() => recheck.mutate()}
+      >
+        <RefreshCw className={recheck.isPending ? "animate-spin" : ""} />
+        Check again
+      </Button>
+    </div>
+  );
+}

package/components/Settings/SetupSection.tsx

@@ -3,6 +3,7 @@
 import { Button } from "@/components/ui/button";
 import { HealthList } from "@/components/Welcome/HealthList";
 import { AgentList } from "@/components/Welcome/AgentList";
+import { ReachRow } from "@/components/Reach/ReachRow";
 import { settingsUiActions } from "@/stores/settingsUi";
 import { welcomeUiActions } from "@/stores/welcomeUi";
 
@@ -32,6 +33,7 @@ export function SetupSection() {
       <div className="flex flex-col gap-2">
         <h3 className="text-sm font-medium">Health</h3>
         <HealthList />
+        <ReachRow />
       </div>
       <div className="flex flex-col gap-2">
         <h3 className="text-sm font-medium">Agents on this machine</h3>

package/components/Welcome/ConnectBlock.tsx

@@ -18,6 +18,7 @@ import {
   CONNECT_STATE,
   connectView,
 } from "@/lib/connect/view";
+import { ReachRow } from "@/components/Reach/ReachRow";
 import { Block } from "./Block";
 
 const COMMAND = "agent-os connect";
@@ -155,6 +156,7 @@ export function ConnectBlock() {
             {update.error && (
               <p className="text-destructive text-xs">{update.error.message}</p>
             )}
+            <ReachRow className="mt-2 px-0" />
           </div>
           <Switch
             checked={wanted ?? view.on}

package/content/tips.json

@@ -536,6 +536,16 @@
         "anchor": "whats-new"
       },
       "added": "2026-10-31"
+    },
+    {
+      "id": "reach-check",
+      "title": "Can't reach your machine?",
+      "body": "Run agent-os check on the computer. It names the cause, like a stopped server or Wi-Fi access being off, and the one line that fixes it.",
+      "guide": {
+        "file": "reachability",
+        "anchor": "run-the-check"
+      },
+      "added": "2026-10-31"
     }
   ]
 }

package/content/whats-new.json

@@ -1865,6 +1865,38 @@
       "area": "Updates",
       "text": "Update notices now appear as a small pop-up instead of a bar across the top of the app.",
       "url": "https://github.com/saadnvd1/agent-os/pull/543"
+    },
+    {
+      "id": 544,
+      "date": "2026-10-31",
+      "kind": "new",
+      "area": "AgentOS",
+      "text": "Run agent-os setup to get your phone connected in a few steps, and agent-os check tells you why a device can't reach your computer and how to fix it.",
+      "url": "https://github.com/saadnvd1/agent-os/pull/544"
+    },
+    {
+      "id": 545,
+      "date": "2026-10-31",
+      "kind": "improved",
+      "area": "AgentOS",
+      "text": "The session list loads much faster, especially on a phone.",
+      "url": "https://github.com/saadnvd1/agent-os/pull/545"
+    },
+    {
+      "id": 546,
+      "date": "2026-10-31",
+      "kind": "fixed",
+      "area": "AgentOS",
+      "text": "Session list rows in the installed phone app no longer lose their short task prompt.",
+      "url": "https://github.com/saadnvd1/agent-os/pull/546"
+    },
+    {
+      "id": 547,
+      "date": "2026-10-31",
+      "kind": "fixed",
+      "area": "AgentOS",
+      "text": "The reachability check now tells a stuck AgentOS apart from another program on its port, and setup keeps a copy of a startup file you edited before replacing it.",
+      "url": "https://github.com/saadnvd1/agent-os/pull/547"
     }
   ]
 }

package/data/devices/queries.ts

@@ -3,6 +3,7 @@ import type { ListedDevice } from "@/lib/security/devices";
 import type { NetworkState } from "@/lib/security/network-state";
 import type { PairingOffer } from "@/lib/security/pair-qr";
 import { deviceKeys } from "./keys";
+import { reachKeys } from "../reach";
 import { provePresence } from "../presence";
 
 async function json<T>(res: Response): Promise<T> {
@@ -77,7 +78,11 @@ export function useUpdateNetwork() {
           }),
         })
       ),
-    onSuccess: (data) => queryClient.setQueryData(deviceKeys.network(), data),
+    onSuccess: (data) => {
+      queryClient.setQueryData(deviceKeys.network(), data);
+      // Wi-Fi access or Connect changed: whether devices get in did too.
+      void queryClient.invalidateQueries({ queryKey: reachKeys.all });
+    },
   });
 }
 

package/data/reach/index.ts

@@ -0,0 +1,33 @@
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import type { ReachReport } from "@/lib/reach/types";
+
+export const reachKeys = {
+  all: ["reach"] as const,
+};
+
+async function fetchReach(fresh: boolean) {
+  const res = await fetch(fresh ? "/api/reach?fresh" : "/api/reach");
+  if (!res.ok)
+    throw new Error(
+      "Couldn't check whether other devices can reach this machine"
+    );
+  return (await res.json()) as ReachReport;
+}
+
+export function useReachQuery(enabled = true) {
+  return useQuery({
+    queryKey: reachKeys.all,
+    queryFn: () => fetchReach(false),
+    enabled,
+    staleTime: 30_000,
+    refetchOnMount: "always",
+  });
+}
+
+export function useRecheckReach() {
+  const client = useQueryClient();
+  return useMutation({
+    mutationFn: () => fetchReach(true),
+    onSuccess: (report) => client.setQueryData(reachKeys.all, report),
+  });
+}