@saadnvd1/agent-os 0.3.509 → 0.3.510

package/README.md

@@ -485,6 +485,17 @@ and the same actions in each row's menu; a row becomes the task's own row
 when it starts. Why it works
 this way: [docs/decisions/2026-10-10-queued-tasks.md](docs/decisions/2026-10-10-queued-tasks.md).
 
+A paired device's token can run the building loop through read-only routes:
+`GET /api/start-options?projectId=` (agents and models, the models a task can
+run on, machines, branches, whether a task plans first, in one request),
+`GET /api/tasks/<id>/diff` (the task's whole change, base to head: a file list,
+then `?file=<path>` for one file's patch; capped, with `truncated` when a cap
+is hit; read from the worktree, else the PR), and `GET /api/tasks/<id>/checks`
+(the PR head's checks, the tail of a failing job's log, and the review gate's
+verdict). A task's `plan` in `GET /api/tasks` carries `status` (`writing`,
+`ready` or `approved`), a title and capped text. Their shapes are in
+`lib/tasks/loop-types.ts`, which has no server imports so a client can share it.
+
 ## Model routing
 
 Each kind of work AgentOS launches an agent for runs on its own model, set in

package/app/api/git/check/route.ts

@@ -1,10 +1,5 @@
 import { NextRequest, NextResponse } from "next/server";
-import {
-  isGitRepo,
-  getBranches,
-  getDefaultBranch,
-  getCurrentBranch,
-} from "@/lib/git";
+import { gitCheck } from "@/lib/git";
 
 /**
  * POST /api/git/check
@@ -19,31 +14,7 @@ export async function POST(request: NextRequest) {
       return NextResponse.json({ error: "Path is required" }, { status: 400 });
     }
 
-    // Check if it's a git repo
-    const isRepo = await isGitRepo(dirPath);
-
-    if (!isRepo) {
-      return NextResponse.json({
-        isGitRepo: false,
-        branches: [],
-        defaultBranch: null,
-        currentBranch: null,
-      });
-    }
-
-    // Get branch info
-    const [branches, defaultBranch, currentBranch] = await Promise.all([
-      getBranches(dirPath),
-      getDefaultBranch(dirPath),
-      getCurrentBranch(dirPath),
-    ]);
-
-    return NextResponse.json({
-      isGitRepo: true,
-      branches,
-      defaultBranch,
-      currentBranch,
-    });
+    return NextResponse.json(await gitCheck(dirPath));
   } catch (error) {
     console.error("Error checking git repo:", error);
     return NextResponse.json(

package/app/api/projects/[id]/machines/route.ts

@@ -1,8 +1,6 @@
 import { NextResponse } from "next/server";
 import { getProject } from "@/lib/projects";
-import { projectRef } from "@/lib/tasks/project-ref";
-import { projectOnPeers } from "@/lib/hosts/peer-actions";
-import { linkedHostIds } from "@/lib/hosts/remote-api";
+import { projectMachines } from "@/lib/hosts/project-machines";
 
 // Which linked machines can take a session for this project, and why not
 // where one can't: { machines: { [hostId]: reason | null } }.
@@ -13,19 +11,5 @@ export async function GET(
   const project = getProject((await params).id);
   if (!project || project.is_uncategorized)
     return NextResponse.json({ error: "Project not found" }, { status: 404 });
-  if ((project.host_id || "local") !== "local")
-    return NextResponse.json({ machines: {} });
-  try {
-    return NextResponse.json({
-      machines: await projectOnPeers(await projectRef(project)),
-    });
-  } catch {
-    // A project outside the home folder has no place on another machine.
-    const reason = "Its folder is outside your home folder";
-    return NextResponse.json({
-      machines: Object.fromEntries(
-        [...linkedHostIds()].map((id) => [id, reason])
-      ),
-    });
-  }
+  return NextResponse.json({ machines: await projectMachines(project) });
 }

package/app/api/start-options/route.ts

@@ -0,0 +1,22 @@
+import { NextRequest, NextResponse } from "next/server";
+import { startOptions, UnknownProjectError } from "@/lib/start-options";
+
+// GET /api/start-options?projectId= - everything the start form needs in
+// one request: agents and their models, the models a task can run on, the
+// machines, the project's branches and whether a task plans first. Without
+// a project, the options for a scratch chat.
+export async function GET(request: NextRequest) {
+  try {
+    return NextResponse.json(
+      await startOptions(request.nextUrl.searchParams.get("projectId") || null)
+    );
+  } catch (error) {
+    if (error instanceof UnknownProjectError)
+      return NextResponse.json({ error: error.message }, { status: 404 });
+    console.error("Reading start options:", error);
+    return NextResponse.json(
+      { error: "Couldn't read the start options" },
+      { status: 500 }
+    );
+  }
+}

package/app/api/tasks/[id]/checks/route.ts

@@ -0,0 +1,37 @@
+import { NextRequest, NextResponse } from "next/server";
+import { db, queries, type Session } from "@/lib/db";
+import { taskChecks } from "@/lib/tasks/checks-view";
+import { LoopError, localTask } from "@/lib/tasks/loop-error";
+import { isMirror } from "@/lib/tasks/remote";
+
+// GET /api/tasks/:id/checks - the PR head's checks, the tail of a failing
+// job's log, and the review gate's verdict on the head. ?log=0 leaves the
+// logs out. Log and verdict text is untrusted: show it, never run it.
+export async function GET(
+  request: NextRequest,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  try {
+    const { id } = await params;
+    const session = localTask(
+      queries.getSession(db).get(id) as Session | undefined,
+      isMirror
+    );
+    return NextResponse.json(
+      await taskChecks(session, {
+        logs: request.nextUrl.searchParams.get("log") !== "0",
+      })
+    );
+  } catch (error) {
+    if (error instanceof LoopError)
+      return NextResponse.json(
+        { error: error.message },
+        { status: error.status }
+      );
+    console.error("Reading a task's checks:", error);
+    return NextResponse.json(
+      { error: "Couldn't read the task's checks" },
+      { status: 500 }
+    );
+  }
+}

package/app/api/tasks/[id]/diff/route.ts

@@ -0,0 +1,35 @@
+import { NextRequest, NextResponse } from "next/server";
+import { db, queries, type Session } from "@/lib/db";
+import { taskDiff } from "@/lib/tasks/diff";
+import { LoopError, localTask } from "@/lib/tasks/loop-error";
+import { isMirror } from "@/lib/tasks/remote";
+
+// GET /api/tasks/:id/diff - the task's whole change, base to head: a file
+// list with status and line counts; with ?file=<path>, that file's patch.
+// Sizes are capped and say "truncated" when a cap was hit.
+export async function GET(
+  request: NextRequest,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  try {
+    const { id } = await params;
+    const session = localTask(
+      queries.getSession(db).get(id) as Session | undefined,
+      isMirror
+    );
+    return NextResponse.json(
+      await taskDiff(session, request.nextUrl.searchParams.get("file"))
+    );
+  } catch (error) {
+    if (error instanceof LoopError)
+      return NextResponse.json(
+        { error: error.message },
+        { status: error.status }
+      );
+    console.error("Reading a task's diff:", error);
+    return NextResponse.json(
+      { error: "Couldn't read the task's change" },
+      { status: 500 }
+    );
+  }
+}

package/data/models/index.ts

@@ -112,14 +112,4 @@ export function useCompareQuery(days: number, enabled = true) {
 }
 
 // Every model a role can be set to: each usable provider's, as references.
-export function modelChoices(effective: EffectiveModels | undefined) {
-  return (effective?.providers ?? [])
-    .filter((p) => p.enabled)
-    .flatMap((p) =>
-      p.models.map((m) => ({
-        ref: `${p.id}/${m}`,
-        label: m,
-        provider: p.label,
-      }))
-    );
-}
+export { modelChoices } from "@/lib/models/choices";

package/lib/git.ts

@@ -148,3 +148,27 @@ export async function renameBranch(
     { timeout: 10000 }
   );
 }
+
+export interface GitCheck {
+  isGitRepo: boolean;
+  branches: string[];
+  defaultBranch: string | null;
+  currentBranch: string | null;
+}
+
+/** Whether a path is a repository, and its branches. */
+export async function gitCheck(dirPath: string): Promise<GitCheck> {
+  if (!(await isGitRepo(dirPath)))
+    return {
+      isGitRepo: false,
+      branches: [],
+      defaultBranch: null,
+      currentBranch: null,
+    };
+  const [branches, defaultBranch, currentBranch] = await Promise.all([
+    getBranches(dirPath),
+    getDefaultBranch(dirPath),
+    getCurrentBranch(dirPath),
+  ]);
+  return { isGitRepo: true, branches, defaultBranch, currentBranch };
+}

package/lib/hosts/project-machines.ts

@@ -0,0 +1,19 @@
+import type { Project } from "../db";
+import { projectRef } from "../tasks/project-ref";
+import { projectOnPeers } from "./peer-actions";
+import { linkedHostIds } from "./remote-api";
+
+// Which linked machines can take a session for this project, and why not
+// where one can't: { [hostId]: reason | null }.
+export async function projectMachines(
+  project: Project
+): Promise<Record<string, string | null>> {
+  if ((project.host_id || "local") !== "local") return {};
+  try {
+    return await projectOnPeers(await projectRef(project));
+  } catch {
+    // A project outside the home folder has no place on another machine.
+    const reason = "Its folder is outside your home folder";
+    return Object.fromEntries([...linkedHostIds()].map((id) => [id, reason]));
+  }
+}

package/lib/models/choices.ts

@@ -0,0 +1,17 @@
+import type { EffectiveModels } from "./config";
+
+// The "provider/model" refs a task can run on: every model of each enabled
+// provider.
+export function modelChoices(
+  effective: Pick<EffectiveModels, "providers"> | undefined
+) {
+  return (effective?.providers ?? [])
+    .filter((p) => p.enabled)
+    .flatMap((p) =>
+      p.models.map((m) => ({
+        ref: `${p.id}/${m}`,
+        label: m,
+        provider: p.label,
+      }))
+    );
+}

package/lib/orchestrator/repo.ts

@@ -88,7 +88,7 @@ async function fetchBranches(
 }
 
 // origin/<branch> when it's there, else a local <branch>.
-async function existingRef(
+export async function existingRef(
   repo: string,
   branch: string
 ): Promise<string | null> {

package/lib/orchestrator/signoff.ts

@@ -43,7 +43,7 @@ const short = (sha: string) => sha.slice(0, 7);
 
 // The heads AgentOS's own restack, or its automatic rebase onto the base,
 // moved the task's branch between.
-function restackedOf(task: Session) {
+export function restackedOf(task: Session) {
   const item = stackQueries.itemForSession(db, task.id);
   if (item) return { from: item.restacked_from, to: item.restacked_to };
   return task.rebased_to

package/lib/start-options.ts

@@ -0,0 +1,93 @@
+/**
+ * What the start form needs in one request: the agents and their models, the
+ * models a task can run on, the machines, the default branch and whether a
+ * task plans first. Built from the helpers the web form already uses; never
+ * a provider's address or key reference, nor a machine's ssh target.
+ */
+
+import { AGENT_OPTIONS } from "./agent-options";
+import { probeAgents } from "./agents/probe";
+import { gitCheck } from "./git";
+import { listHosts } from "./hosts";
+import { projectMachines } from "./hosts/project-machines";
+import { getModelOptions, getDefaultModelForAgent } from "./model-catalog";
+import { effectiveModels } from "./models/config";
+import { modelChoices } from "./models/choices";
+import { resolveRole } from "./models/resolve";
+import { getProject } from "./projects";
+import { expandHome } from "./tasks/session";
+import { taskRouting } from "./tasks";
+import type { StartOptions } from "./tasks/loop-types";
+
+const BRANCHES_MAX = 50;
+
+export class UnknownProjectError extends Error {}
+
+export async function startOptions(
+  projectId: string | null
+): Promise<StartOptions> {
+  const project = projectId ? getProject(projectId) : undefined;
+  if (projectId && (!project || project.is_uncategorized))
+    throw new UnknownProjectError("Project not found");
+  const here = !project || (project.host_id || "local") === "local";
+  const models = effectiveModels();
+
+  let planDefault = false;
+  let planError: string | null = null;
+  const roles = { plan: "", implement: "" };
+  try {
+    const opts = { workspaceId: project?.workspace_id ?? null };
+    roles.plan = resolveRole("plan", opts, models).ref;
+    roles.implement = resolveRole("implement", opts, models).ref;
+    planDefault = taskRouting(opts.workspaceId, "chat", undefined).plan;
+  } catch (error) {
+    planError = error instanceof Error ? error.message : String(error);
+  }
+
+  const [probes, git, machines] = await Promise.all([
+    here ? probeAgents() : Promise.resolve(null),
+    project && here
+      ? gitCheck(expandHome(project.working_directory))
+      : Promise.resolve(null),
+    project
+      ? projectMachines(project)
+      : Promise.resolve<Record<string, string | null>>({}),
+  ]);
+
+  return {
+    project: project
+      ? {
+          id: project.id,
+          name: project.name,
+          agentType: project.agent_type,
+          defaultModel: project.default_model,
+          hostId: project.host_id || "local",
+        }
+      : null,
+    agents: AGENT_OPTIONS.map((a) => ({
+      value: a.value,
+      label: a.label,
+      installed: probes?.[a.value]?.installed ?? null,
+      auth: probes?.[a.value]?.auth ?? null,
+      hint: probes?.[a.value]?.hint ?? null,
+      models: getModelOptions(a.value),
+      defaultModel: getDefaultModelForAgent(a.value),
+    })),
+    taskModels: modelChoices(models),
+    roles,
+    planDefault,
+    planError,
+    hosts: listHosts().map((h) => ({
+      id: h.id,
+      name: h.name,
+      linked: h.id === "local" || Boolean(h.linked),
+      unavailable: machines[h.id] ?? null,
+    })),
+    git: git && {
+      isGitRepo: git.isGitRepo,
+      defaultBranch: git.defaultBranch,
+      currentBranch: git.currentBranch,
+      branches: git.branches.slice(0, BRANCHES_MAX),
+    },
+  };
+}

package/lib/tasks/checks-view.ts

@@ -0,0 +1,192 @@
+/**
+ * A task's PR checks for the phone: each check's name, state, link and
+ * duration, the tail of a failing Actions job's log (the same one AgentOS
+ * sends a task when its CI fails), and the review gate's verdict on the head.
+ * Log and verdict text is untrusted: displayed, never run.
+ */
+
+import { getCheck } from "../orchestrator/checks";
+import { restackedOf } from "../orchestrator/signoff";
+import { run, settledRollup } from "./gh";
+import { failedLog, repoOfPR, type FailedLog } from "./pr-activity";
+import { prFor, projectPathFor, storedPR } from "./session";
+import type { RollupEntry } from "./state";
+import {
+  CHECK_LOGS_MAX,
+  CHECK_LOG_MAX_BYTES,
+  parseReviewDetail,
+  type CheckState,
+  type TaskCheck,
+  type TaskChecks,
+  type TaskReviewVerdict,
+} from "./loop-types";
+import type { Session } from "../db";
+
+const outcome = (c: RollupEntry) =>
+  (c.conclusion || c.state || c.status || "").toUpperCase();
+
+export function checkState(c: RollupEntry): CheckState {
+  switch (outcome(c)) {
+    case "SUCCESS":
+      return "pass";
+    case "FAILURE":
+    case "ERROR":
+    case "TIMED_OUT":
+    case "ACTION_REQUIRED":
+      return "fail";
+    case "SKIPPED":
+      return "skipped";
+    case "CANCELLED":
+      return "cancelled";
+    case "NEUTRAL":
+    case "STALE":
+      return "neutral";
+    default:
+      return "pending";
+  }
+}
+
+// gh gives a run not finished yet a zero completedAt (0001-01-01).
+const time = (t?: string | null) => {
+  const ms = Date.parse(t || "");
+  return ms > 0 ? ms : null;
+};
+const iso = (t?: string | null) => {
+  const ms = time(t);
+  return ms === null ? null : new Date(ms).toISOString();
+};
+
+// A status context can carry any URL; only a web one is a link.
+const httpsUrl = (u?: string | null) =>
+  u && /^https:\/\/[^\s]+$/.test(u) ? u : null;
+
+export function toTaskChecks(rollup: RollupEntry[]): TaskCheck[] {
+  return rollup.map((c) => {
+    const start = time(c.startedAt);
+    const end = time(c.completedAt);
+    return {
+      name: c.name ?? c.context ?? "(unnamed)",
+      workflow: c.workflowName || null,
+      state: checkState(c),
+      conclusion: (c.conclusion || c.state || null)?.toLowerCase() ?? null,
+      url: httpsUrl(c.detailsUrl),
+      startedAt: iso(c.startedAt),
+      completedAt: iso(c.completedAt),
+      durationSec:
+        start !== null && end !== null && end >= start
+          ? Math.round((end - start) / 1000)
+          : null,
+    };
+  });
+}
+
+// A finished job's log never changes.
+const logCache = new Map<string, FailedLog | null>();
+const LOG_CACHE_MAX = 200;
+export const resetLogCache = () => logCache.clear();
+
+export interface ChecksDeps {
+  failedLog: typeof failedLog;
+}
+
+export async function taskChecks(
+  session: Session,
+  opts: { logs?: boolean; deps?: ChecksDeps } = {}
+): Promise<TaskChecks> {
+  const deps = opts.deps ?? { failedLog };
+  const dir = projectPathFor(session);
+  const live = session.task_status === "running";
+  const pr = dir
+    ? live
+      ? await prFor(session).catch(() => null)
+      : storedPR(session)
+    : null;
+  if (!pr || !dir) return { pr: null, checks: [], review: null };
+  const head = pr.head ?? null;
+
+  let checks: TaskCheck[] = [];
+  let rollup: RollupEntry[] = [];
+  try {
+    const out = JSON.parse(
+      await run(
+        "gh",
+        [
+          "pr",
+          "view",
+          String(pr.number),
+          "--json",
+          "headRefOid,statusCheckRollup",
+        ],
+        dir,
+        20000
+      )
+    ) as { headRefOid?: string; statusCheckRollup?: RollupEntry[] | null };
+    rollup = out.statusCheckRollup ?? [];
+    if (pr.state === "OPEN")
+      rollup = await settledRollup(dir, pr.url, out.headRefOid, rollup);
+    checks = toTaskChecks(rollup);
+  } catch (error) {
+    console.error(`Reading ${session.name}'s checks:`, error);
+  }
+
+  const repo = repoOfPR(pr.url);
+  if (opts.logs !== false && repo) {
+    const failing = checks
+      .map((c, i) => ({ c, url: c.state === "fail" ? c.url : null, i }))
+      .filter((x) => x.url)
+      .slice(0, CHECK_LOGS_MAX);
+    await Promise.all(
+      failing.map(async ({ c, url }) => {
+        let log = logCache.get(url!);
+        if (log === undefined) {
+          log = await deps.failedLog(dir, repo, url).catch((error) => {
+            console.error(`Reading ${session.name}'s CI log:`, error);
+            return null;
+          });
+          if (log) {
+            if (logCache.size >= LOG_CACHE_MAX) logCache.clear();
+            logCache.set(url!, log);
+          }
+        }
+        if (log) {
+          const tail = log.tail.slice(-CHECK_LOG_MAX_BYTES);
+          c.log = {
+            step: log.step,
+            tail,
+            truncated: tail.length < log.tail.length,
+          };
+        }
+      })
+    );
+  }
+
+  return {
+    pr: { number: pr.number, url: pr.url, state: pr.state, head },
+    checks,
+    review: head ? reviewVerdict(session, head) : null,
+  };
+}
+
+// The review covering the head: its own, or the one of the head the task
+// pushed while the head is exactly the one AgentOS restacked it to.
+export function reviewVerdict(
+  session: Session,
+  head: string
+): TaskReviewVerdict | null {
+  const restacked = restackedOf(session);
+  const row =
+    getCheck(session.id, head, "review") ??
+    (restacked?.to === head && restacked.from
+      ? getCheck(session.id, restacked.from, "review")
+      : null);
+  if (!row) return null;
+  const { summary, findings, truncated } = parseReviewDetail(row.detail);
+  return {
+    sha: row.sha,
+    status: row.status,
+    summary,
+    findings,
+    at: row.created_at,
+    truncated,
+  };
+}

package/lib/tasks/diff.ts

@@ -0,0 +1,259 @@
+/**
+ * A task's whole change, base branch to head (merge-base), for the phone to
+ * review: a file list with status and line counts, then one file's patch.
+ * Read from the task's worktree when it's there, else from its PR on GitHub.
+ * Sizes are capped and say so; a file is only ever one the change lists.
+ */
+
+import { git, isGitError, resolveRef } from "../git-exec";
+import { getDefaultBranch, isGitRepo, isBranchName } from "../git";
+import { existingRef } from "../orchestrator/repo";
+import { run } from "./gh";
+import { repoOfPR } from "./pr-activity";
+import { localWorktree, projectPathFor } from "./session";
+import { LoopError } from "./loop-error";
+import {
+  DIFF_MAX_FILES,
+  DIFF_PATCH_MAX_BYTES,
+  type TaskDiffFile,
+  type TaskDiffList,
+  type TaskDiffPatch,
+} from "./loop-types";
+import type { Session } from "../db";
+
+export interface DiffCaps {
+  files: number;
+  patchBytes: number;
+}
+const CAPS: DiffCaps = {
+  files: DIFF_MAX_FILES,
+  patchBytes: DIFF_PATCH_MAX_BYTES,
+};
+
+const MAX_PATH_BYTES = 1024;
+
+/** A path the change could list: relative, inside the repo, no tricks. */
+export function validDiffPath(file: unknown): file is string {
+  if (typeof file !== "string" || !file) return false;
+  if (Buffer.byteLength(file) > MAX_PATH_BYTES) return false;
+  if (file.includes("\0") || file.includes("\\")) return false;
+  if (file.startsWith("/") || file.startsWith("-")) return false;
+  return !file.split("/").some((part) => part === ".." || part === "");
+}
+
+const STATUS_OF_GITHUB: Record<string, string> = {
+  added: "A",
+  removed: "D",
+  modified: "M",
+  changed: "M",
+  renamed: "R",
+  copied: "C",
+};
+
+interface Source {
+  kind: "worktree" | "pr";
+  base: string;
+  head: string;
+  list: () => Promise<TaskDiffFile[]>;
+  patch: (file: string) => Promise<{ patch: string | null; tooLarge: boolean }>;
+}
+
+// `git diff --numstat -z` and `--name-status -z`, joined by path.
+function parseGit(numstat: string, nameStatus: string): TaskDiffFile[] {
+  const status = new Map<string, string>();
+  const parts = nameStatus.split("\0");
+  for (let i = 0; i + 1 < parts.length; i += 2)
+    status.set(parts[i + 1], parts[i][0] || "M");
+  const files: TaskDiffFile[] = [];
+  for (const row of numstat.split("\0")) {
+    const m = /^(\d+|-)\t(\d+|-)\t([\s\S]+)$/.exec(row);
+    if (!m) continue;
+    const binary = m[1] === "-";
+    files.push({
+      path: m[3],
+      status: status.get(m[3]) ?? "M",
+      additions: binary ? null : Number(m[1]),
+      deletions: binary ? null : Number(m[2]),
+      binary,
+    });
+  }
+  return files;
+}
+
+async function worktreeSource(
+  session: Session,
+  dir: string,
+  caps: DiffCaps
+): Promise<Source> {
+  if (!(await isGitRepo(dir))) throw new LoopError("No repository", 404);
+  const recorded = session.base_branch || (await getDefaultBranch(dir));
+  if (!isBranchName(recorded)) throw new LoopError("Unknown base branch", 404);
+  const base = await existingRef(dir, recorded);
+  if (!base) throw new LoopError("The base branch isn't here", 404);
+  const head = (await resolveRef(dir, "HEAD")) ?? "";
+  const range = `${base}...HEAD`;
+  const flags = ["--no-renames", "--no-ext-diff", "--no-textconv"];
+  return {
+    kind: "worktree",
+    base: recorded,
+    head,
+    list: async () => {
+      const [numstat, names] = await Promise.all([
+        git(dir, ["diff", "--numstat", "-z", ...flags, range, "--"]),
+        git(dir, ["diff", "--name-status", "-z", ...flags, range, "--"]),
+      ]);
+      return parseGit(numstat, names);
+    },
+    patch: async (file) => {
+      try {
+        const out = await git(
+          dir,
+          ["diff", "--no-color", ...flags, range, "--", file],
+          { literalPathspecs: true, maxBuffer: caps.patchBytes * 4 }
+        );
+        return { patch: out, tooLarge: false };
+      } catch (error) {
+        if (
+          isGitError(error) &&
+          error.code === "ERR_CHILD_PROCESS_STDIO_MAXBUFFER"
+        )
+          return { patch: null, tooLarge: true };
+        throw error;
+      }
+    },
+  };
+}
+
+interface GithubFile {
+  filename?: string;
+  status?: string;
+  additions?: number;
+  deletions?: number;
+  patch?: string;
+}
+
+async function prSource(session: Session): Promise<Source> {
+  const repo = session.pr_url ? repoOfPR(session.pr_url) : null;
+  const dir = projectPathFor(session);
+  if (!repo || !session.pr_number || !dir)
+    throw new LoopError("The task has no worktree and no pull request", 404);
+  const slug = `${repo.owner}/${repo.name}`;
+  const meta = JSON.parse(
+    await run(
+      "gh",
+      [
+        "pr",
+        "view",
+        String(session.pr_number),
+        "--repo",
+        slug,
+        "--json",
+        "baseRefName,headRefOid",
+      ],
+      dir,
+      15000
+    )
+  ) as { baseRefName?: string; headRefOid?: string };
+  const pages = async (): Promise<GithubFile[]> => {
+    const all: GithubFile[] = [];
+    for (let page = 1; page <= 3; page++) {
+      const rows = JSON.parse(
+        await run(
+          "gh",
+          [
+            "api",
+            `repos/${slug}/pulls/${session.pr_number}/files?per_page=100&page=${page}`,
+          ],
+          dir,
+          30000
+        )
+      ) as GithubFile[];
+      all.push(...rows);
+      if (rows.length < 100) break;
+    }
+    return all;
+  };
+  let cached: GithubFile[] | null = null;
+  const rows = async () => (cached ??= await pages());
+  return {
+    kind: "pr",
+    base: meta.baseRefName ?? "",
+    head: meta.headRefOid ?? "",
+    list: async () =>
+      (await rows())
+        .filter((f) => typeof f.filename === "string")
+        .map((f) => ({
+          path: f.filename!,
+          status: STATUS_OF_GITHUB[f.status ?? ""] ?? "M",
+          additions: f.additions ?? 0,
+          deletions: f.deletions ?? 0,
+          binary: false,
+        })),
+    patch: async (file) => {
+      const hit = (await rows()).find((f) => f.filename === file);
+      return typeof hit?.patch === "string"
+        ? { patch: hit.patch, tooLarge: false }
+        : { patch: null, tooLarge: true };
+    },
+  };
+}
+
+async function sourceFor(session: Session, caps: DiffCaps): Promise<Source> {
+  const dir = localWorktree(session);
+  if (dir) return worktreeSource(session, dir, caps);
+  return prSource(session);
+}
+
+// Cut at a line break at or before `max` bytes.
+export function capPatch(
+  patch: string,
+  max: number
+): { patch: string; truncated: boolean } {
+  if (Buffer.byteLength(patch) <= max) return { patch, truncated: false };
+  const cut = Buffer.from(patch).subarray(0, max).toString("utf8");
+  const nl = cut.lastIndexOf("\n");
+  return { patch: nl > 0 ? cut.slice(0, nl) : cut, truncated: true };
+}
+
+/** The file list, or with `file` that one file's patch. */
+export async function taskDiff(
+  session: Session,
+  file?: string | null,
+  caps: DiffCaps = CAPS
+): Promise<TaskDiffList | TaskDiffPatch> {
+  if (file != null && !validDiffPath(file))
+    throw new LoopError("Not a path in the change", 400);
+  const source = await sourceFor(session, caps);
+  const all = await source.list();
+  if (file != null) {
+    if (!all.some((f) => f.path === file))
+      throw new LoopError("That file isn't in the change", 404);
+    const { patch, tooLarge } = await source.patch(file);
+    if (patch === null)
+      return {
+        source: source.kind,
+        path: file,
+        patch: null,
+        truncated: true,
+        tooLarge: true,
+      };
+    const capped = capPatch(patch, caps.patchBytes);
+    return {
+      source: source.kind,
+      path: file,
+      patch: capped.patch,
+      truncated: capped.truncated,
+      tooLarge,
+    };
+  }
+  return {
+    source: source.kind,
+    base: source.base,
+    head: source.head,
+    files: all.slice(0, caps.files),
+    totalFiles: all.length,
+    additions: all.reduce((n, f) => n + (f.additions ?? 0), 0),
+    deletions: all.reduce((n, f) => n + (f.deletions ?? 0), 0),
+    truncated: all.length > caps.files,
+  };
+}

package/lib/tasks/gh.ts

@@ -133,7 +133,7 @@ const RUN_CACHE_MAX = 2000;
 // The rollup with stale reruns dropped. Only a check that ran more than once
 // costs an API call, one per workflow run attempt. A run outside the PR's
 // repo, or one the API can't describe, leaves its check unsettled.
-async function settledRollup(
+export async function settledRollup(
   repoDir: string,
   prUrl: string,
   head: string | undefined,

package/lib/tasks/index.ts

@@ -47,6 +47,8 @@ import { expandHome, prFor, storedPR, taskSessions } from "./session";
 import { InProgressError } from "./move-bundle";
 import { nameFor } from "../session-titles";
 import { taskSetupOf, type TaskSetup } from "./setup";
+import { taskPlan } from "./plan-view";
+import type { TaskPlan } from "./loop-types";
 import { finishTaskStart } from "./start";
 import { isRemoteHost } from "../hosts";
 import { DEFAULT_START_VIEW, type StartView } from "../sessions/launch";
@@ -98,7 +100,8 @@ export interface TaskView {
   model?: string;
   planning?: boolean;
   // What its starter decided about a plan step, and why; null if unstated.
-  plan?: { planned: boolean; reason: string | null } | null;
+  // Its plan: ready to read or approve, with a title and capped text.
+  plan?: TaskPlan | null;
   // A quick change: the orchestrator session that makes it (no agent).
   quickOf?: string | null;
   // What it has cost so far in weighted tokens (lib/usage/weights).
@@ -389,13 +392,7 @@ export async function taskView(session: Session): Promise<TaskView> {
     armed: !!session.merge_armed_at,
     model: sessionModelRef(session),
     planning: session.plan_phase === "planning",
-    plan:
-      session.plan_decided == null
-        ? null
-        : {
-            planned: !!session.plan_decided,
-            reason: session.plan_reason ?? null,
-          },
+    plan: taskPlan(session),
     quickOf: session.quick_of ?? null,
   };
 }

package/lib/tasks/loop-error.ts

@@ -0,0 +1,21 @@
+// A refusal the loop routes turn into a status code.
+export class LoopError extends Error {
+  constructor(
+    message: string,
+    readonly status: 400 | 404 | 409
+  ) {
+    super(message);
+    this.name = "LoopError";
+  }
+}
+
+/** The task a route names: unknown, not a task, or another machine's. */
+export function localTask<T extends { task_status?: string | null }>(
+  session: T | undefined,
+  mirror: (s: T) => boolean
+): T {
+  if (!session?.task_status) throw new LoopError("Task not found", 404);
+  if (mirror(session))
+    throw new LoopError("That task runs on another machine", 409);
+  return session;
+}

package/lib/tasks/loop-types.ts

@@ -0,0 +1,202 @@
+/**
+ * The shapes the building-loop endpoints answer with (start options, a
+ * task's diff, its checks and review verdict, its plan), plus their caps.
+ * Pure data, no imports, so the native app can sync this file on its own.
+ * Every string that came from a log, a review or a plan is untrusted text
+ * to display, never to run.
+ */
+
+export const DIFF_MAX_FILES = 300;
+export const DIFF_PATCH_MAX_BYTES = 200_000;
+export const CHECK_LOG_MAX_BYTES = 8_000;
+export const CHECK_LOGS_MAX = 3;
+export const REVIEW_DETAIL_MAX = 20_000;
+export const REVIEW_FINDINGS_MAX = 50;
+export const PLAN_TEXT_MAX = 4_000;
+
+// -- Start options ---------------------------------------------------------
+
+export interface StartAgent {
+  value: string;
+  label: string;
+  // On this machine; null when the project runs on another machine.
+  installed: boolean | null;
+  auth: string | null;
+  hint: string | null;
+  models: { value: string; label: string }[];
+  defaultModel: string;
+}
+
+export interface StartHost {
+  id: string;
+  name: string;
+  linked: boolean;
+  // Why a project here can't go to this machine, when it can't.
+  unavailable: string | null;
+}
+
+export interface TaskModelChoice {
+  ref: string;
+  label: string;
+  provider: string;
+}
+
+export interface StartOptions {
+  project: {
+    id: string;
+    name: string;
+    agentType: string;
+    defaultModel: string;
+    hostId: string;
+  } | null;
+  agents: StartAgent[];
+  // "provider/model" refs a task can run on, and the role defaults.
+  taskModels: TaskModelChoice[];
+  roles: { plan: string; implement: string };
+  planDefault: boolean;
+  planError: string | null;
+  hosts: StartHost[];
+  git: {
+    isGitRepo: boolean;
+    defaultBranch: string | null;
+    currentBranch: string | null;
+    branches: string[];
+  } | null;
+}
+
+// -- A task's whole change -------------------------------------------------
+
+export interface TaskDiffFile {
+  path: string;
+  // git's letters: A added, M modified, D deleted, R renamed, C copied,
+  // T type changed.
+  status: string;
+  // null for a binary file.
+  additions: number | null;
+  deletions: number | null;
+  binary: boolean;
+}
+
+export interface TaskDiffList {
+  source: "worktree" | "pr";
+  base: string;
+  head: string;
+  files: TaskDiffFile[];
+  totalFiles: number;
+  additions: number;
+  deletions: number;
+  truncated: boolean;
+}
+
+export interface TaskDiffPatch {
+  source: "worktree" | "pr";
+  path: string;
+  patch: string | null;
+  truncated: boolean;
+  // No patch to show: binary, or too big for git or GitHub to give.
+  tooLarge: boolean;
+}
+
+// -- Checks and the review verdict ----------------------------------------
+
+export type CheckState =
+  | "pass"
+  | "fail"
+  | "pending"
+  | "skipped"
+  | "cancelled"
+  | "neutral";
+
+export interface TaskCheck {
+  name: string;
+  workflow: string | null;
+  state: CheckState;
+  conclusion: string | null;
+  url: string | null;
+  startedAt: string | null;
+  completedAt: string | null;
+  durationSec: number | null;
+  // The failed step's log around its error, for a failing Actions job.
+  log?: { step: string | null; tail: string; truncated: boolean };
+}
+
+export interface ReviewFinding {
+  severity: string;
+  file: string | null;
+  line: number | null;
+  summary: string;
+}
+
+export interface TaskReviewVerdict {
+  sha: string;
+  status: "running" | "pass" | "block" | "error";
+  summary: string;
+  findings: ReviewFinding[];
+  at: string;
+  truncated: boolean;
+}
+
+export interface TaskChecks {
+  pr: {
+    number: number;
+    url: string;
+    state: string;
+    head: string | null;
+  } | null;
+  checks: TaskCheck[];
+  review: TaskReviewVerdict | null;
+}
+
+// -- A task's plan ---------------------------------------------------------
+
+export interface TaskPlan {
+  // As the starter decided (null reason when unstated).
+  planned: boolean;
+  reason: string | null;
+  // null: no plan document yet.
+  status: "writing" | "ready" | "approved" | null;
+  source: "step" | "chat" | null;
+  title: string | null;
+  // Relative to the task's worktree.
+  path: string | null;
+  text: string | null;
+  truncated: boolean;
+}
+
+// Splits a stored review detail (lib/orchestrator/review-prompt.ts writes
+// "summary" then "- [severity] file:line: text" lines) back into a summary and
+// findings. A line that isn't a finding stays in the summary.
+const FINDING = /^- \[([^\]\n]{1,40})\](?: ([^\s:]+)(?::(\d+))?)?: (.*)$/;
+
+export function parseReviewDetail(detail: string | null | undefined): {
+  summary: string;
+  findings: ReviewFinding[];
+  truncated: boolean;
+} {
+  let truncated = false;
+  let text = detail ?? "";
+  if (text.length > REVIEW_DETAIL_MAX) {
+    text = text.slice(0, REVIEW_DETAIL_MAX);
+    truncated = true;
+  }
+  const summary: string[] = [];
+  const findings: ReviewFinding[] = [];
+  for (const line of text.split("\n")) {
+    const m = FINDING.exec(line);
+    if (!m) {
+      summary.push(line);
+      continue;
+    }
+    if (findings.length >= REVIEW_FINDINGS_MAX) {
+      truncated = true;
+      continue;
+    }
+    findings.push({
+      severity: m[1],
+      file: m[2] ?? null,
+      line: m[3] ? Number(m[3]) : null,
+      summary: m[4],
+    });
+  }
+  return { summary: summary.join("\n").trim(), findings, truncated };
+}

package/lib/tasks/plan-view.ts

@@ -0,0 +1,127 @@
+/**
+ * A task's plan as the list shows it: whether one is being written, waits for
+ * a decision, or was approved, with its title and a capped piece of text.
+ * Two sources: a chat in plan mode proposes one (a "plan" item, carried out
+ * when approved), and the plan step writes one to a file in the worktree.
+ */
+
+import fs from "fs";
+import path from "path";
+import { db, type Session } from "../db";
+import { PLAN_FILE, planSummary } from "../models/plan-step";
+import { PLAN_TEXT_MAX, type TaskPlan } from "./loop-types";
+import { expandHome } from "./session";
+
+const TITLE_MAX = 120;
+
+export function planTitle(text: string): string | null {
+  const heading = /^#{1,6}\s+(.+)$/m.exec(text)?.[1]?.trim();
+  const title = heading ?? planSummary(text, 1)[0] ?? null;
+  if (!title) return null;
+  return title.length > TITLE_MAX ? `${title.slice(0, TITLE_MAX - 1)}…` : title;
+}
+
+function chatPlan(
+  sessionId: string
+): { text: string; carried: boolean } | null {
+  const row = db
+    .prepare(
+      `SELECT data FROM chat_items WHERE session_id = ?
+         AND json_extract(data, '$.kind') = 'plan' ORDER BY seq DESC LIMIT 1`
+    )
+    .get(sessionId) as { data: string } | undefined;
+  if (!row) return null;
+  try {
+    const item = JSON.parse(row.data) as { plan?: unknown; carried?: boolean };
+    return typeof item.plan === "string"
+      ? { text: item.plan, carried: !!item.carried }
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+// Only the first `max` bytes, not the whole file.
+function readHead(file: string, max: number): string | null {
+  let fd: number | undefined;
+  try {
+    fd = fs.openSync(file, "r");
+    const buf = Buffer.alloc(max + 1);
+    const n = fs.readSync(fd, buf, 0, max + 1, 0);
+    return buf.subarray(0, n).toString("utf8");
+  } catch {
+    return null;
+  } finally {
+    if (fd !== undefined) fs.closeSync(fd);
+  }
+}
+
+function capped(text: string) {
+  const over = text.length > PLAN_TEXT_MAX;
+  return { text: over ? text.slice(0, PLAN_TEXT_MAX) : text, truncated: over };
+}
+
+export function taskPlan(session: Session): TaskPlan | null {
+  const decided = session.plan_decided ?? null;
+  const phase = session.plan_phase ?? null;
+  // Only a chat in plan mode is asked: listing tasks must stay cheap.
+  const maybeChat = !!session.chat_plan;
+  if (decided === null && !phase && !maybeChat) return null;
+
+  const base = {
+    planned: decided === null ? false : !!decided,
+    reason: session.plan_reason ?? null,
+  };
+  const none = {
+    ...base,
+    status: null,
+    source: null,
+    title: null,
+    path: null,
+    text: null,
+    truncated: false,
+  } satisfies TaskPlan;
+
+  const chat = maybeChat ? chatPlan(session.id) : null;
+  if (chat && !chat.carried)
+    return {
+      ...base,
+      planned: true,
+      status: "ready",
+      source: "chat",
+      title: planTitle(chat.text),
+      path: null,
+      ...capped(chat.text),
+    };
+
+  if (phase && session.worktree_path) {
+    const file = path.join(expandHome(session.worktree_path), PLAN_FILE);
+    const text = readHead(file, PLAN_TEXT_MAX);
+    if (text !== null || phase === "planning") {
+      const body = text ?? "";
+      return {
+        ...base,
+        planned: true,
+        status: phase === "planning" ? "writing" : "approved",
+        source: "step",
+        title: planTitle(body),
+        path: text !== null ? PLAN_FILE : null,
+        ...capped(body),
+      };
+    }
+  }
+
+  if (chat)
+    return {
+      ...base,
+      planned: true,
+      status: "approved",
+      source: "chat",
+      title: planTitle(chat.text),
+      path: null,
+      ...capped(chat.text),
+    };
+
+  if (decided === null) return null;
+  return none;
+}

package/lib/tasks/session.ts

@@ -37,7 +37,7 @@ export function projectPathFor(session: Session): string | null {
 
 // The task's worktree, when it's here to look at: null when it's gone or on
 // another host.
-function localWorktree(session: Session): string | null {
+export function localWorktree(session: Session): string | null {
   if (!session.worktree_path) return null;
   if (session.host_id && session.host_id !== "local") return null;
   const dir = expandHome(session.worktree_path);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saadnvd1/agent-os",
-  "version": "0.3.509",
+  "version": "0.3.510",
   "description": "Self-hosted web UI for managing Claude Code sessions",
   "bin": {
     "agent-os": "scripts/agent-os"