@saadnvd1/agent-os 0.3.766 → 0.3.770

package/app/api/sessions/resolve/route.test.ts

@@ -0,0 +1,81 @@
+import { randomUUID } from "crypto";
+import { beforeEach, describe, expect, it } from "vitest";
+import { NextRequest } from "next/server";
+import { getDb } from "@/lib/db";
+import { GET } from "./route";
+
+const get = (query: string) =>
+  GET(new NextRequest(`http://localhost/api/sessions/resolve?${query}`));
+
+function insert(
+  id: string,
+  name: string,
+  over: { archived?: boolean; created?: string } = {}
+) {
+  getDb()
+    .prepare(
+      `INSERT INTO sessions (id, name, tmux_name, created_at, archived_at)
+       VALUES (?, ?, ?, ?, ?)`
+    )
+    .run(
+      id,
+      name,
+      `claude-${id}`,
+      over.created ?? "2026-10-01 10:00:00",
+      over.archived ? "2026-10-02 10:00:00" : null
+    );
+}
+
+// Prefixes no random uuid in the shared test database starts with.
+const P = "fffe0001";
+const Q = "fffe0002";
+
+beforeEach(() => {
+  getDb().prepare(`DELETE FROM sessions WHERE id LIKE 'fffe000%'`).run();
+});
+
+describe("GET /api/sessions/resolve", () => {
+  it("resolves a short id, archived sessions included", async () => {
+    const id = `${P}-1111-4111-8111-111111111111`;
+    insert(id, "Web perf audit", { archived: true });
+    const res = await get(`ref=${P}&slug=whatever`);
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({
+      id,
+      name: "Web perf audit",
+      archived: true,
+    });
+  });
+
+  it("resolves a whole id", async () => {
+    const id = randomUUID();
+    insert(id, "Plain");
+    const res = await get(`ref=${id}`);
+    expect((await res.json()).id).toBe(id);
+    getDb().prepare(`DELETE FROM sessions WHERE id = ?`).run(id);
+  });
+
+  it("breaks a prefix clash by slug, then by newest", async () => {
+    const older = `${Q}-1111-4111-8111-111111111111`;
+    const newer = `${Q}-2222-4222-8222-222222222222`;
+    insert(older, "Fix login", { created: "2026-10-01 10:00:00" });
+    insert(newer, "Ship docs", { created: "2026-10-03 10:00:00" });
+    expect((await (await get(`ref=${Q}&slug=fix-login`)).json()).id).toBe(
+      older
+    );
+    expect((await (await get(`ref=${Q}&slug=ship-docs`)).json()).id).toBe(
+      newer
+    );
+    expect((await (await get(`ref=${Q}&slug=gone-name`)).json()).id).toBe(
+      newer
+    );
+    expect((await (await get(`ref=${Q}`)).json()).id).toBe(newer);
+  });
+
+  it("is 404 for an unknown id and 400 for a malformed or short ref", async () => {
+    expect((await get(`ref=fffe0009`)).status).toBe(404);
+    for (const bad of ["", "ref=", "ref=fffe", "ref=fffe00", "ref=<script>"]) {
+      expect((await get(bad)).status).toBe(400);
+    }
+  });
+});

package/app/api/sessions/resolve/route.ts

@@ -0,0 +1,14 @@
+import { NextRequest, NextResponse } from "next/server";
+import { refFromParams, resolveSessionRef } from "@/lib/sessions/resolve";
+
+// GET /api/sessions/resolve?ref=<id8|id>[&slug=] - the session a link names,
+// archived ones included: {id, name, archived}.
+export async function GET(request: NextRequest) {
+  const params = request.nextUrl.searchParams;
+  const ref = refFromParams(params.get("ref"), params.get("slug"));
+  if (!ref) return NextResponse.json({ error: "bad ref" }, { status: 400 });
+  const session = resolveSessionRef(ref);
+  if (!session)
+    return NextResponse.json({ error: "not found" }, { status: 404 });
+  return NextResponse.json(session);
+}

package/components/Chat/ChatPanel.tsx

@@ -66,7 +66,7 @@ import { useGoToItem } from "./useGoToItem";
 import { NeedsYouStrip } from "@/components/Orchestrator/NeedsYouStrip";
 import { useResolveQuestion } from "@/data/orchestrators";
 import { needsYouFocus, needsYouFocusActions } from "@/stores/needsYouFocus";
-import { hrefWithSession } from "@/lib/session-url";
+import { openSessionById } from "./session-link";
 import { questionSource } from "@/lib/chat/turns";
 import { useViewport } from "@/hooks/useViewport";
 import { useChatCommands } from "./useChatCommands";
@@ -767,15 +767,9 @@ export function ChatPanel({
               if (item.kind === "ask") needsYouFocusActions.ask(item.ask.id);
               else if (item.kind === "chat") toEnd();
               else if (item.kind === "task" || item.kind === "card") {
-                window.history.pushState(
-                  null,
-                  "",
-                  hrefWithSession(
-                    location.href,
-                    item.kind === "task" ? item.sessionId : item.card.sessionId
-                  )
+                openSessionById(
+                  item.kind === "task" ? item.sessionId : item.card.sessionId
                 );
-                window.dispatchEvent(new PopStateEvent("popstate"));
               } else goTo((all) => questionSource(all, item.question.text));
             }}
             onReply={(item) => {

package/components/Chat/EventRow.tsx

@@ -12,7 +12,7 @@ import {
 } from "lucide-react";
 import type { ChatItem, ChatOrigin, ChatOriginKind } from "@/lib/chat/events";
 import { eventParts, originOf } from "@/lib/chat/origin";
-import { hrefWithSession } from "@/lib/session-url";
+import { SessionAnchor } from "./SessionAnchor";
 import { cn } from "@/lib/utils";
 import { UserMessage } from "./Messages";
 import { openSessionLink as openSession } from "./session-link";
@@ -45,8 +45,8 @@ function Source({ origin }: { origin: ChatOrigin }) {
   if (!origin.sessionId) return name;
   const id = origin.sessionId;
   return (
-    <a
-      href={hrefWithSession("/", id)}
+    <SessionAnchor
+      sessionId={id}
       onClick={(e) => {
         e.stopPropagation();
         openSession(e, id);
@@ -54,7 +54,7 @@ function Source({ origin }: { origin: ChatOrigin }) {
       className="hover:text-foreground relative min-w-0 underline-offset-2 before:absolute before:-inset-x-1 before:-inset-y-3.5 hover:underline"
     >
       {name}
-    </a>
+    </SessionAnchor>
   );
 }
 

package/components/Chat/Messages.tsx

@@ -20,7 +20,7 @@ import { cn } from "@/lib/utils";
 import { leadingCommand } from "@/lib/chat/commands";
 import { compactedLine } from "@/lib/chat/stale";
 import { splitProse, splitUserText } from "@/lib/chat/user-text";
-import { inAppSessionId } from "@/lib/session-url";
+import { inAppSessionRef } from "@/lib/session-url";
 import { CodeBlock } from "./Code";
 import { CopyButton } from "./CopyButton";
 import { FileChip } from "./FileChip";
@@ -42,16 +42,16 @@ import {
 type Of<K extends ChatItem["kind"]> = Extract<ChatItem, { kind: K }>;
 
 function UserLink({ href }: { href: string }) {
-  const id =
+  const ref =
     typeof window === "undefined"
       ? null
-      : inAppSessionId(href, window.location.origin);
+      : inAppSessionRef(href, window.location.origin);
   return (
     <a
       href={href}
-      target={id ? undefined : "_blank"}
-      rel={id ? undefined : "noopener noreferrer"}
-      onClick={id ? (e) => openSessionLink(e, id) : undefined}
+      target={ref ? undefined : "_blank"}
+      rel={ref ? undefined : "noopener noreferrer"}
+      onClick={ref ? (e) => openSessionLink(e, ref) : undefined}
       className="chat-link font-medium"
     >
       {href}

package/components/Chat/SessionAnchor.tsx

@@ -0,0 +1,22 @@
+"use client";
+
+import type { AnchorHTMLAttributes } from "react";
+import { useSessionHref } from "@/hooks/useSessionHref";
+import { openSessionLink } from "./session-link";
+
+type Props = Omit<AnchorHTMLAttributes<HTMLAnchorElement>, "href"> & {
+  sessionId: string;
+};
+
+// A link to a session at its readable address. A plain click opens it here;
+// a modified one, a new tab. An own onClick replaces the open.
+export function SessionAnchor({ sessionId, onClick, ...rest }: Props) {
+  const href = useSessionHref(sessionId);
+  return (
+    <a
+      href={href}
+      onClick={onClick ?? ((e) => openSessionLink(e, sessionId))}
+      {...rest}
+    />
+  );
+}

package/components/Chat/session-link.ts

@@ -1,10 +1,27 @@
 import type { MouseEvent } from "react";
-import { hrefWithSession } from "@/lib/session-url";
+import {
+  hrefWithRef,
+  hrefWithSession,
+  type SessionRef,
+} from "@/lib/session-url";
 
-// Opens the session through its address, the way a shared link does.
-export function openSessionLink(e: MouseEvent<HTMLAnchorElement>, id: string) {
+// Opens a session through its address, the way a shared link does. The
+// address it lands on is rewritten to the session's readable one.
+export function openSessionById(id: string): void {
+  go(hrefWithSession(location.href, { id }));
+}
+
+export function openSessionLink(
+  e: MouseEvent<HTMLAnchorElement>,
+  target: string | SessionRef
+) {
   if (e.metaKey || e.ctrlKey || e.shiftKey || e.button !== 0) return;
   e.preventDefault();
-  window.history.pushState(null, "", hrefWithSession(location.href, id));
+  if (typeof target === "string") openSessionById(target);
+  else go(hrefWithRef(location.href, target));
+}
+
+function go(href: string): void {
+  window.history.pushState(null, "", href);
   window.dispatchEvent(new PopStateEvent("popstate"));
 }

package/components/Health/EnvFailures/SessionList.tsx

@@ -2,7 +2,7 @@
 
 import { openSessionLink } from "@/components/Chat/session-link";
 import { compactTimeAgo } from "@/lib/session-meta";
-import { hrefWithSession } from "@/lib/session-url";
+import { sessionPath } from "@/lib/session-url";
 import type { EnvSessionView } from "@/lib/health/env/types";
 
 export function SessionList({
@@ -27,7 +27,7 @@ export function SessionList({
       {sessions.map((s) => (
         <li key={s.sessionId} className="min-h-11 text-sm">
           <a
-            href={hrefWithSession("/", s.sessionId)}
+            href={sessionPath({ id: s.sessionId, name: s.name })}
             onClick={(e) => openSessionLink(e, s.sessionId)}
             className="font-medium underline-offset-2 hover:underline"
           >

package/components/Pane/PaneMenu.tsx

@@ -103,7 +103,7 @@ export function PaneMenu({
                 </div>
               )}
             </DropdownMenuLabel>
-            <DropdownMenuItem onSelect={() => copySessionLink(session.id)}>
+            <DropdownMenuItem onSelect={() => copySessionLink(session)}>
               <Link className="h-4 w-4" />
               Copy link
             </DropdownMenuItem>

package/components/SessionList/QueuedRow.tsx

@@ -12,7 +12,7 @@ import {
   queuedSubtitle,
   type QueuedRow as Row,
 } from "@/lib/sidebar/queued";
-import { sessionLink } from "@/lib/session-url";
+import { SessionAnchor } from "@/components/Chat/SessionAnchor";
 import { cn } from "@/lib/utils";
 import { useRowContext } from "./RowContext";
 import { RowShell, type RowMenuKind } from "./RowShell";
@@ -184,8 +184,8 @@ function QueuedSubtitle({ row }: { row: Row }) {
           (target ? (
             <>
               {" "}
-              <a
-                href={sessionLink("", target)}
+              <SessionAnchor
+                sessionId={target}
                 onClick={(e) => {
                   // The row opens it too; the link alone handles its click.
                   e.stopPropagation();
@@ -198,7 +198,7 @@ function QueuedSubtitle({ row }: { row: Row }) {
                 className="hover:text-foreground underline decoration-dotted underline-offset-2"
               >
                 {after}
-              </a>
+              </SessionAnchor>
             </>
           ) : (
             ` ${after}`

package/components/SessionList/SessionRowMenu.tsx

@@ -191,7 +191,7 @@ export function SessionRowMenu({
           recipesUiActions.openRecipe(recipeRun!.id)
         );
       case "copy-link":
-        return item("Copy link", Link, () => copySessionLink(session.id));
+        return item("Copy link", Link, () => copySessionLink(session));
       case "share":
         return item("Share…", Share2, () =>
           shareUiActions.open({

package/components/Shares/SharedLinksPanel.tsx

@@ -10,6 +10,7 @@ import {
   type SharedLinkRow,
 } from "@/data/shares";
 import { cn } from "@/lib/utils";
+import { SessionAnchor } from "@/components/Chat/SessionAnchor";
 
 const when = (iso: string) =>
   new Date(iso).toLocaleDateString(undefined, {
@@ -44,12 +45,9 @@ function Row({ share }: { share: SharedLinkRow }) {
 
   const title =
     share.kind === "chat" && share.sessionId ? (
-      <a
-        href={`/?session=${encodeURIComponent(share.sessionId)}`}
-        className="hover:underline"
-      >
+      <SessionAnchor sessionId={share.sessionId} className="hover:underline">
         {share.title}
-      </a>
+      </SessionAnchor>
     ) : (
       share.title
     );

package/hooks/useCopyToClipboard.ts

@@ -65,9 +65,12 @@ export async function writeClipboard(text: string): Promise<void> {
 }
 
 // A session's own address (lib/session-url), for a bookmark or another device.
-export async function copySessionLink(sessionId: string): Promise<void> {
+export async function copySessionLink(session: {
+  id: string;
+  name: string;
+}): Promise<void> {
   try {
-    await writeClipboard(sessionLink(window.location.origin, sessionId));
+    await writeClipboard(sessionLink(window.location.origin, session));
     toast.success("Link copied");
   } catch {
     toast.error("Could not copy to clipboard");

package/hooks/useSessionHref.ts

@@ -0,0 +1,20 @@
+"use client";
+
+import { useContext } from "react";
+import { QueryClientContext } from "@tanstack/react-query";
+import { sessionKeys } from "@/data/sessions/keys";
+import type { SessionsResponse } from "@/data/sessions/queries";
+import { sessionPath } from "@/lib/session-url";
+
+/**
+ * A session's address from just its id: readable when the list has its name,
+ * `/s/<id8>` otherwise (opening that fills the slug in). Works without a
+ * query client too: a chat rendered to static markup (an export, a share).
+ */
+export function useSessionHref(id: string): string {
+  const list = useContext(QueryClientContext)?.getQueryData<SessionsResponse>(
+    sessionKeys.list()
+  );
+  const name = list?.sessions.find((s) => s.id === id)?.name;
+  return sessionPath({ id, name });
+}

package/hooks/useSessionUrl.ts

@@ -3,7 +3,12 @@
 import { useCallback, useEffect, useLayoutEffect, useRef } from "react";
 import { toast } from "sonner";
 import type { Session } from "@/lib/db";
-import { SessionUrlSync, locateSession } from "@/lib/session-url";
+import {
+  SessionUrlSync,
+  locateSession,
+  pickSession,
+  type SessionRef,
+} from "@/lib/session-url";
 import { usePanes } from "@/contexts/PaneContext";
 
 interface Options {
@@ -16,9 +21,9 @@ interface Options {
 }
 
 /**
- * The address bar names the focused session (`/?session=<id>`), and an
- * address opens its session: on load, after pairing, and on back/forward.
- * With split panes it follows the focused pane.
+ * The address bar names the focused session (`/s/<name>-<id8>`, following
+ * renames), and an address opens its session: on load, after pairing, and on
+ * back/forward. With split panes it follows the focused pane.
  */
 export function useSessionUrl({
   sessions,
@@ -78,23 +83,22 @@ export function useSessionUrl({
         replace: (href) => window.history.replaceState(null, "", href),
       },
       {
-        isKnown: (id) => latest.current.sessions.some((s) => s.id === id),
+        find: (ref) => pickSession(ref, latest.current.sessions)?.id ?? null,
+        nameOf: (id) =>
+          latest.current.sessions.find((s) => s.id === id)?.name ?? null,
         open: (id) => {
           const session = latest.current.sessions.find((s) => s.id === id);
           if (session) reveal(session);
         },
         // Made a moment ago and not in the list yet: ask once more. Archived,
         // merged and dropped sessions aren't listed and stay not found.
-        openUnlisted: async (id) => {
+        openUnlisted: async (ref) => {
           const fresh = await latest.current.reloadSessions();
-          const session = fresh.find((s) => s.id === id);
+          const session = pickSession(ref, fresh);
           if (session) reveal(session);
           return !!session;
         },
-        notFound: () =>
-          toast.error("Session not found", {
-            description: "It may have been archived or deleted.",
-          }),
+        notFound: (ref) => void explainNotFound(ref),
       }
     );
     return syncRef.current;
@@ -112,6 +116,12 @@ export function useSessionUrl({
     getSync().focusChanged(focusedId);
   }, [getSync, focusedId]);
 
+  // A rename (by hand, or the title a first turn gives it) moves the slug.
+  const focusedName = sessions.find((s) => s.id === focusedId)?.name ?? null;
+  useEffect(() => {
+    if (focusedName !== null) getSync().renamed();
+  }, [getSync, focusedName]);
+
   const ready = hydrated && loaded;
   useEffect(() => {
     if (ready) void getSync().start();
@@ -123,3 +133,22 @@ export function useSessionUrl({
     return () => window.removeEventListener("popstate", onPop);
   }, [getSync]);
 }
+
+// An archived session says so, by name; anything else isn't found.
+async function explainNotFound(ref: SessionRef): Promise<void> {
+  const params = new URLSearchParams(
+    "id" in ref ? { ref: ref.id } : { ref: ref.short, slug: ref.slug ?? "" }
+  );
+  const found = await fetch(`/api/sessions/resolve?${params}`)
+    .then((r) => (r.ok ? r.json() : null))
+    .catch(() => null);
+  if (found?.archived) {
+    toast.error(`${found.name} is on the Done shelf`, {
+      description: "Bring it back from there to open it.",
+    });
+    return;
+  }
+  toast.error("Session not found", {
+    description: "It may have been archived or deleted.",
+  });
+}

package/lib/away/deploy.ts

@@ -8,6 +8,7 @@
  */
 
 import fs from "fs";
+import path from "path";
 import type { ProjectConfig } from "../project-config";
 import { gitFetch, isAncestor } from "../git-exec";
 import { expandHome } from "../tasks/session";
@@ -19,14 +20,22 @@ export type DeployConfig = NonNullable<ProjectConfig["deploy"]>;
 export type DeployVerdict =
   | { state: "ok"; detail: string }
   | { state: "failed"; detail: string }
-  | { state: "pending" }
+  | { state: "pending"; detail?: string }
   | { state: "unchecked"; detail: string };
 
 export const DEPLOY_WITHIN_MIN = 30;
 // After the deploy lands, the server gets this long to answer healthy.
 export const HEALTH_GRACE_MS = 3 * 60 * 1000;
 
+// scripts/autodeploy holds a new head AGENTOS_MIN_GAP seconds after the last
+// restart (`restarted`, next to `deployed`), so a merge isn't late until the
+// gap is over plus this margin.
+export const GAP_MARGIN_MS = 10 * 60 * 1000;
+const DEFAULT_GAP_S = 3600;
+
 export interface DeployDeps {
+  // When the deploy last restarted the server, in ms; null when unknown.
+  restartedAt: (file: string) => number | null;
   // The commit a state file names, or null when there's no such file.
   readSha: (file: string) => { sha: string; at: number } | null;
   // Whether `sha` is in the history of `tip` (fetching it if need be);
@@ -89,7 +98,22 @@ async function health(
   }
 }
 
+function restartedAt(file: string): number | null {
+  try {
+    const s = Number(fs.readFileSync(expandHome(file), "utf-8").trim());
+    return Number.isFinite(s) && s > 0 ? s * 1000 : null;
+  } catch {
+    return null;
+  }
+}
+
+const gapMs = () => {
+  const s = Number(process.env.AGENTOS_MIN_GAP ?? DEFAULT_GAP_S);
+  return (Number.isFinite(s) && s >= 0 ? s : DEFAULT_GAP_S) * 1000;
+};
+
 export const DEFAULT_DEPS: DeployDeps = {
+  restartedAt,
   readSha,
   contains,
   health,
@@ -159,8 +183,21 @@ async function judge(
       state: "failed",
       detail: `the deploy of ${failed.sha.slice(0, 7)} (which has ${short}) failed; see the deploy's log`,
     };
+  // The state files sit together; `restarted` is beside `deployed`.
+  const restarted = deps.restartedAt(
+    path.join(path.dirname(config.deployed), "restarted")
+  );
+  const gapEnd = restarted === null ? 0 : restarted + gapMs();
+  if (gapEnd > input.now)
+    return {
+      state: "pending",
+      detail: `deploy waiting: restart gap, ~${Math.ceil((gapEnd - input.now) / 60000)} min left`,
+    };
   const within = (config.within_minutes ?? DEPLOY_WITHIN_MIN) * 60 * 1000;
-  if (input.now - input.mergedAt >= within)
+  if (
+    input.now - input.mergedAt >= within &&
+    input.now >= gapEnd + GAP_MARGIN_MS
+  )
     return {
       state: "failed",
       detail: `${short} not deployed ${Math.round(within / 60000)} minutes after the merge`,

package/lib/reports/evidence/build.ts

@@ -6,6 +6,7 @@ import type { TaskState } from "../../tasks/state";
 import type { DigestSignals } from "../../analyst/types";
 import { latestChecks } from "../../analyst/signals";
 import type { EvidenceRef } from "../types";
+import { sessionPath } from "../../session-url";
 
 const EXCERPT = 1500;
 const cap = (s: string, n = EXCERPT) =>
@@ -82,7 +83,7 @@ export function testEvidence(
       status: c.passed ? "pass" : "fail",
       at,
       sha: head ?? undefined,
-      href: `/?session=${sessionId}`,
+      href: sessionPath({ id: sessionId }),
     }));
 }
 
@@ -101,7 +102,7 @@ export function diffEvidence(
       label: `${m[3]} (+${m[1] === "-" ? 0 : m[1]} −${m[2] === "-" ? 0 : m[2]})`,
       status: "info",
       at,
-      href: `/?session=${sessionId}`,
+      href: sessionPath({ id: sessionId }),
     });
     if (out.length >= 40) break;
   }
@@ -174,7 +175,7 @@ export function logEvidence(log: {
     status: "pass",
     at: log.createdAt,
     excerpt: log.mergeCommit ? `Merge commit ${log.mergeCommit}` : undefined,
-    href: `/?session=${log.sessionId}`,
+    href: sessionPath({ id: log.sessionId }),
   };
 }
 

package/lib/session-audit/render.ts

@@ -6,6 +6,7 @@
 
 import type { PatternStat, Summary } from "./aggregate";
 import type { AuditFindings } from "./store";
+import { sessionPath } from "../session-url";
 
 export const fmt = (n: number) =>
   n >= 1e9
@@ -245,7 +246,7 @@ export function renderSummary(
         "biggest output (est.)",
       ],
       s.sessions.slice(0, 30).map((x) => [
-        `[${x.id.slice(0, 8)}](/?session=${x.id})`,
+        `[${x.id.slice(0, 8)}](${sessionPath(x)})`,
         x.kind,
         x.name.slice(0, 40),
         x.turns,

package/lib/session-logs/gather.ts

@@ -18,7 +18,7 @@ import { getWorkspace } from "../workspaces";
 import { amendmentsOf } from "../orchestrator/amendments";
 import { PLAN_FILE } from "../models/plan-step";
 import { estimateCost, rowModel } from "../usage/cost";
-import { sessionLink } from "../session-url";
+import { sessionPath } from "../session-url";
 import type { LogData, LogEvent, LogUsageRow } from "./build";
 
 const expandHome = (p: string) => p.replace(/^~/, os.homedir());
@@ -296,6 +296,6 @@ export function gatherLogData(s: Session, opts: GatherOpts = {}): LogData {
     timeline,
     usage: usageRows(s.id),
     outcome: finalMessage(s.id),
-    sessionPath: sessionLink("", s.id),
+    sessionPath: sessionPath(s),
   };
 }

package/lib/session-slug.ts

@@ -0,0 +1,29 @@
+// The readable part of a session's address (`/s/<slug>-<id8>`). Cosmetic:
+// only the short id resolves, so the slug is rebuilt from the current name
+// and a rename never breaks a link. No imports: the browser uses it too.
+
+export const SLUG_MAX = 48;
+export const SHORT_ID_LEN = 8;
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+export const isUuid = (id: string): boolean => UUID.test(id);
+
+/** Lowercase ASCII words joined by `-`; `session` when nothing is left. */
+export function sessionSlug(name: string): string {
+  const words = (name ?? "")
+    .normalize("NFKD")
+    .replace(/\p{M}/gu, "")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  if (!words) return "session";
+  if (words.length <= SLUG_MAX) return words;
+  const cut = words.slice(0, SLUG_MAX);
+  const atWord = cut.lastIndexOf("-");
+  return (atWord > 0 ? cut.slice(0, atWord) : cut).replace(/-+$/, "");
+}
+
+/** The first group of a uuid, lowercase. */
+export const shortId = (id: string): string =>
+  id.slice(0, SHORT_ID_LEN).toLowerCase();

package/lib/session-url.ts

@@ -1,50 +1,152 @@
-// Every session has its own address: `/?session=<id>`. The id, not the name:
-// names change, ids don't. Nothing here grants access; the page behind the
-// address is behind the device gate like any other.
+// Every session has its own address: `/s/<slug>-<id8>`, the slug made from
+// its name and id8 the first group of its uuid. Only the id resolves: the
+// slug is rebuilt from the current name, so a rename never breaks a link,
+// and a stale one is rewritten in place. `/?session=<id>`, the address before,
+// still opens and is rewritten the same way. Nothing here grants access; the
+// page behind the address is behind the device gate like any other.
 
 import { getAllPaneIds, type PaneState } from "./panes";
+import { isUuid, sessionSlug, shortId, SHORT_ID_LEN } from "./session-slug";
 
 export const SESSION_PARAM = "session";
+export const SESSION_PATH = "/s/";
 
 // Ids are uuids today; anything id-shaped is accepted so other machines'
 // sessions fit too. Everything else in the address is ignored.
 const ID_SHAPE = /^[A-Za-z0-9_-]{1,128}$/;
+const SHORT = new RegExp(`^[0-9a-f]{${SHORT_ID_LEN}}$`);
+const SLUG = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+// The one path segment of `/s/<ref>`.
+const REF_PATH = /^\/s\/([A-Za-z0-9-]{1,200})$/;
 
 // The site-relative origin used to parse paths with URL.
 const BASE = "http://agentos.invalid";
 
-export function sessionIdFromHref(href: string): string | null {
-  const id = new URL(href, BASE).searchParams.get(SESSION_PARAM);
-  return id && ID_SHAPE.test(id) ? id : null;
+/** What an address names: a whole id, or a short id and its (cosmetic) slug. */
+export type SessionRef =
+  { id: string } | { short: string; slug: string | null };
+
+/** A session as links need it: the name only makes the slug. */
+export interface SessionLinkable {
+  id: string;
+  name?: string | null;
+}
+
+function refFromSegment(segment: string): SessionRef | null {
+  if (isUuid(segment)) return { id: segment.toLowerCase() };
+  const lower = segment.toLowerCase();
+  const dash = lower.lastIndexOf("-");
+  const short = lower.slice(dash + 1);
+  if (!SHORT.test(short)) return null;
+  const slug = dash > 0 ? lower.slice(0, dash) : null;
+  if (slug !== null && !SLUG.test(slug)) return null;
+  return { short, slug };
+}
+
+export function sessionRefFromHref(href: string): SessionRef | null {
+  const url = new URL(href, BASE);
+  const m = REF_PATH.exec(url.pathname);
+  if (m) return refFromSegment(m[1]);
+  const id = url.searchParams.get(SESSION_PARAM);
+  return id && ID_SHAPE.test(id) ? { id } : null;
+}
+
+/** Whether a ref could name this id (the slug isn't consulted). */
+export function refMatches(ref: SessionRef, id: string): boolean {
+  if ("id" in ref) return ref.id === id || ref.id === id.toLowerCase();
+  return isUuid(id) && id.toLowerCase().startsWith(ref.short);
+}
+
+/**
+ * The session a ref names among these: the one id, else the one with the
+ * prefix, else (two sharing a prefix) the one whose slug matches, then the
+ * newest.
+ */
+export function pickSession<
+  T extends { id: string; name: string; created_at?: string | null },
+>(ref: SessionRef, sessions: readonly T[]): T | null {
+  const found = sessions.filter((s) => refMatches(ref, s.id));
+  if (found.length <= 1) return found[0] ?? null;
+  if ("short" in ref && ref.slug) {
+    const bySlug = found.filter((s) => sessionSlug(s.name) === ref.slug);
+    if (bySlug.length === 1) return bySlug[0];
+    if (bySlug.length > 1) return newest(bySlug);
+  }
+  return newest(found);
+}
+
+const newest = <T extends { created_at?: string | null }>(xs: T[]): T =>
+  xs.reduce((a, b) => ((b.created_at ?? "") > (a.created_at ?? "") ? b : a));
+
+/**
+ * A session's address: `/s/<slug>-<id8>`, or `/s/<id8>` when the name isn't
+ * at hand (opening it fills the slug in). An id that isn't a uuid keeps the
+ * old `/?session=<id>`.
+ */
+export function sessionPath(s: SessionLinkable): string {
+  if (!isUuid(s.id)) return `/?${SESSION_PARAM}=${encodeURIComponent(s.id)}`;
+  const short = shortId(s.id);
+  return s.name == null
+    ? `${SESSION_PATH}${short}`
+    : `${SESSION_PATH}${sessionSlug(s.name)}-${short}`;
+}
+
+/** The address a ref names as it stands, slug and all. */
+export function refPath(ref: SessionRef): string {
+  if ("id" in ref) return sessionPath({ id: ref.id });
+  const slug = ref.slug ? `${ref.slug}-` : "";
+  return `${SESSION_PATH}${slug}${ref.short}`;
 }
 
-/** The same address with the session set (or removed), as path+query+hash. */
-export function hrefWithSession(href: string, id: string | null): string {
+function hrefWithPath(href: string, path: string | null): string {
   const url = new URL(href, BASE);
-  if (id) url.searchParams.set(SESSION_PARAM, id);
-  else url.searchParams.delete(SESSION_PARAM);
+  url.searchParams.delete(SESSION_PARAM);
+  const target = new URL(path ?? "/", BASE);
+  url.pathname = target.pathname;
+  target.searchParams.forEach((v, k) => url.searchParams.set(k, v));
   return url.pathname + url.search + url.hash;
 }
 
+/**
+ * The same address showing this session (or none), as path+query+hash. Every
+ * other query param (`?settings=`, `?welcome=`) stays.
+ */
+export function hrefWithSession(
+  href: string,
+  s: SessionLinkable | null
+): string {
+  return hrefWithPath(href, s ? sessionPath(s) : null);
+}
+
+/** The same address showing the session a ref names. */
+export function hrefWithRef(href: string, ref: SessionRef): string {
+  return hrefWithPath(href, refPath(ref));
+}
+
 /** The session a link to this same instance opens, or null for any other link. */
-export function inAppSessionId(href: string, origin: string): string | null {
+export function inAppSessionRef(
+  href: string,
+  origin: string
+): SessionRef | null {
   let url: URL;
   try {
     url = new URL(href);
   } catch {
     return null;
   }
-  if (url.origin !== origin || url.pathname !== "/") return null;
-  return sessionIdFromHref(href);
+  if (url.origin !== origin) return null;
+  if (url.pathname !== "/" && !url.pathname.startsWith(SESSION_PATH))
+    return null;
+  return sessionRefFromHref(href);
 }
 
-export function sessionLink(origin: string, id: string): string {
-  return `${origin}/?${SESSION_PARAM}=${encodeURIComponent(id)}`;
+export function sessionLink(origin: string, s: SessionLinkable): string {
+  return `${origin}${sessionPath(s)}`;
 }
 
 /**
  * The address to come back to after pairing, or null. Only the app's own
- * page with a query survives: what a link to a session is. Checked after
+ * page survives: `/` with a query, or a session's `/s/<ref>`. Checked after
  * parsing, as `/.//host` and the like resolve to another host.
  */
 export function safeNextPath(raw: string | null | undefined): string | null {
@@ -55,7 +157,9 @@ export function safeNextPath(raw: string | null | undefined): string | null {
   } catch {
     return null;
   }
-  if (url.origin !== BASE || url.pathname !== "/" || !url.search) return null;
+  if (url.origin !== BASE) return null;
+  if (REF_PATH.test(url.pathname)) return url.pathname + url.search;
+  if (url.pathname !== "/" || !url.search) return null;
   return "/" + url.search;
 }
 
@@ -94,8 +198,10 @@ export interface SessionUrlEnv {
 }
 
 export interface SessionUrlDeps {
-  /** A session the sidebar lists. */
-  isKnown(id: string): boolean;
+  /** The listed session a ref names, or null. */
+  find(ref: SessionRef): string | null;
+  /** A listed session's current name, for its address. */
+  nameOf(id: string): string | null;
   /** Show a listed session. */
   open(id: string): void;
   /**
@@ -103,9 +209,9 @@ export interface SessionUrlDeps {
    * found and opened. Archived, merged and dropped sessions aren't listed and
    * stay not found.
    */
-  openUnlisted(id: string): Promise<boolean>;
+  openUnlisted(ref: SessionRef): Promise<boolean>;
   /** The address named a session that can't be opened. */
-  notFound(id: string): void;
+  notFound(ref: SessionRef): void;
 }
 
 /**
@@ -115,13 +221,15 @@ export interface SessionUrlDeps {
  *
  * A switch away from a live session pushes an entry, so back returns to it.
  * Anything else replaces: the first sync, leaving a session that was archived
- * or deleted, and leaving a sessionless address.
+ * or deleted, leaving a sessionless address, and rewriting an address that
+ * names the shown session another way (an old `?session=`, a stale slug, a
+ * rename).
  */
 export class SessionUrlSync {
   private started = false;
   // A session the address asked for, until it's the one focused (or the
   // open plainly didn't land).
-  private pending: string | null = null;
+  private pending: SessionRef | null = null;
   private pendingUntil = 0;
   private focused: string | null = null;
 
@@ -134,8 +242,8 @@ export class SessionUrlSync {
   /** Once panes and sessions are loaded: follow the address it opened with. */
   async start(): Promise<void> {
     if (this.started) return;
-    const id = sessionIdFromHref(this.env.href());
-    if (id) await this.go(id);
+    const ref = sessionRefFromHref(this.env.href());
+    if (ref) await this.go(ref);
     this.started = true;
     if (!this.pending) this.sync();
   }
@@ -144,42 +252,56 @@ export class SessionUrlSync {
   focusChanged(id: string | null): void {
     this.focused = id;
     if (this.pending && this.now() < this.pendingUntil) {
-      if (id !== this.pending) return;
+      if (!id || !refMatches(this.pending, id)) return;
     }
     this.pending = null;
     if (this.started) this.sync();
   }
 
+  /** The focused session's name changed: the address takes the new slug. */
+  renamed(): void {
+    if (this.started && !this.pending) this.write("replace");
+  }
+
   /** Back or forward landed on another entry. */
   async popstate(): Promise<void> {
     if (!this.started) return;
-    const id = sessionIdFromHref(this.env.href());
-    if (id && id !== this.focused) await this.go(id);
+    const ref = sessionRefFromHref(this.env.href());
+    if (ref) {
+      const id = this.deps.find(ref);
+      if (!id || id !== this.focused) await this.go(ref);
+    }
     // An entry with no session, or one that couldn't open: say what's shown.
     if (!this.pending) this.write("replace");
   }
 
-  private async go(id: string): Promise<void> {
-    if (id === this.focused) return;
-    this.pending = id;
+  private async go(ref: SessionRef): Promise<void> {
+    const id = this.deps.find(ref);
+    if (id && id === this.focused) return;
+    this.pending = ref;
     this.pendingUntil = this.now() + PENDING_MS;
-    if (this.deps.isKnown(id)) return this.deps.open(id);
-    const opened = await this.deps.openUnlisted(id).catch(() => false);
+    if (id) return this.deps.open(id);
+    const opened = await this.deps.openUnlisted(ref).catch(() => false);
     if (opened) return;
-    if (this.pending === id) this.pending = null;
-    this.deps.notFound(id);
+    if (this.pending === ref) this.pending = null;
+    this.deps.notFound(ref);
   }
 
   private sync(): void {
-    const current = sessionIdFromHref(this.env.href());
-    if (current === this.focused) return;
-    this.write(current && this.deps.isKnown(current) ? "push" : "replace");
+    const ref = sessionRefFromHref(this.env.href());
+    const current = ref && this.deps.find(ref);
+    this.write(current && current !== this.focused ? "push" : "replace");
   }
 
   private write(mode: "push" | "replace"): void {
     const href = this.env.href();
-    if (sessionIdFromHref(href) === this.focused) return;
-    const next = hrefWithSession(href, this.focused);
+    const id = this.focused;
+    const next = hrefWithSession(
+      href,
+      id ? { id, name: this.deps.nameOf(id) ?? undefined } : null
+    );
+    const url = new URL(href, BASE);
+    if (next === url.pathname + url.search + url.hash) return;
     if (mode === "push") this.env.push(next);
     else this.env.replace(next);
   }

package/lib/sessions/resolve.ts

@@ -0,0 +1,55 @@
+// The session a link's ref names, archived ones included: what the page asks
+// when its list doesn't have it (lib/session-url).
+
+import { db } from "../db";
+import { pickSession, type SessionRef } from "../session-url";
+import { isUuid, SHORT_ID_LEN } from "../session-slug";
+
+export interface ResolvedSession {
+  id: string;
+  name: string;
+  archived: boolean;
+}
+
+interface Row {
+  id: string;
+  name: string;
+  archived_at: string | null;
+  created_at: string | null;
+}
+
+const ID_SHAPE = /^[A-Za-z0-9_-]{1,128}$/;
+const SHORT = new RegExp(`^[0-9a-f]{${SHORT_ID_LEN}}$`);
+const SLUG = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+
+/** The ref a request's `ref` and `slug` params name, or null when malformed. */
+export function refFromParams(
+  ref: string | null,
+  slug: string | null
+): SessionRef | null {
+  if (!ref) return null;
+  if (SHORT.test(ref)) {
+    return { short: ref, slug: slug && SLUG.test(slug) ? slug : null };
+  }
+  // A whole id; never a shorter prefix, which would let a caller walk the table.
+  if (isUuid(ref) || (ID_SHAPE.test(ref) && ref.length > SHORT_ID_LEN))
+    return { id: ref };
+  return null;
+}
+
+export function resolveSessionRef(ref: SessionRef): ResolvedSession | null {
+  const cols = `id, name, archived_at, created_at`;
+  const rows =
+    "id" in ref
+      ? (db
+          .prepare(`SELECT ${cols} FROM sessions WHERE id = ?`)
+          .all(ref.id) as Row[])
+      : // A range on the key, so the index finds the prefix.
+        (db
+          .prepare(`SELECT ${cols} FROM sessions WHERE id >= ? AND id < ?`)
+          .all(ref.short, `${ref.short}~`) as Row[]);
+  const hit = pickSession(ref, rows);
+  return hit
+    ? { id: hit.id, name: hit.name, archived: hit.archived_at !== null }
+    : null;
+}

package/lib/settings-url.ts

@@ -1,6 +1,6 @@
 // Settings has its own address: `/?settings=<section>`, or a bare
 // `?settings` for the list (a phone) or the first section. It sits beside
-// `?session=`, so a link can name both.
+// a session's address (`/s/<name>-<id8>`), so a link can name both.
 
 export const SETTINGS_PARAM = "settings";
 

package/lib/tasks/contract/plan.ts

@@ -25,7 +25,7 @@ import { getProject } from "../../projects";
 import { planFor, splitOf } from "../../plans/features";
 import { moveTask } from "../move-flow";
 import * as client from "./client";
-import { meetsNeeds, needsOf } from "../placement";
+import { meetsNeeds, needsOf, taskPinnedToMac } from "../placement";
 import { remotePlanPath } from "./plan-path";
 import { DEFAULT_PRIORITY, isPriority } from "../schedule-types";
 import { localHolds } from "../hold-checks";
@@ -55,6 +55,9 @@ function checkedSplit(s: Session, text: string | null) {
   }
 }
 
+const pinned = (s: Session, project: { working_directory: string }) =>
+  taskPinnedToMac(s.id, expandHome(project.working_directory));
+
 /**
  * Where a written plan is built: "there" (approved on the machine that
  * planned it) or "home" (moved here first). Pieces are checked against this
@@ -70,6 +73,9 @@ export function implementTarget(
   // The project lives there: nothing here to build it in.
   if (!project || isRemoteHost(project.host_id)) return "there";
   if (split) return "home";
+  // An explicit Mac pin builds on the Mac, wherever the plan ran.
+  if (pinned(s, project))
+    return meetsNeeds(["mac"], machineCapabilities()) ? "home" : "there";
   const { needs } = needsOf({
     projectId: project.id,
     projectPath: expandHome(project.working_directory),
@@ -229,6 +235,7 @@ export async function handoffHome(
     projectPath: expandHome(project.working_directory),
     prompt: s.task_prompt ?? "",
   });
+  if (pinned(s, project) && !needs.includes("mac")) needs.push("mac");
   const holds = localHolds(
     {
       needs,

package/lib/tasks/placement.ts

@@ -79,6 +79,28 @@ export function inferNeeds(projectPath: string): Need[] {
   return [];
 }
 
+// Whether the starter asked for a Mac outright: the request's `machine`
+// (stored on the queue row, which shares the task's id), a recipe's, or the
+// project's own machine setting. A need read from the brief or the files
+// doesn't count: that one a plan can ignore.
+export function pinnedToMac(
+  stored: string | null,
+  projectPath: string
+): boolean {
+  const asked = parseNeeds(stored);
+  if (asked) return asked.includes("mac");
+  return !!loadProjectConfig(projectPath).config.machine?.needs?.includes(
+    "mac"
+  );
+}
+
+export function taskPinnedToMac(taskId: string, projectPath: string): boolean {
+  const row = db
+    .prepare(`SELECT machine_needs FROM task_queue WHERE id = ?`)
+    .get(taskId) as { machine_needs: string | null } | undefined;
+  return pinnedToMac(row?.machine_needs ?? null, projectPath);
+}
+
 export function needsOf(input: {
   projectId: string;
   projectPath: string;

package/lib/tasks/queue-placement.ts

@@ -13,6 +13,7 @@ import { usesGitCrypt } from "../worktree-add";
 import { list as hostTasks } from "./contract/client";
 import {
   asPlanPhase,
+  pinnedToMac,
   place,
   unplaceable,
   wantsPlacing,
@@ -90,11 +91,22 @@ async function peerOptions(
   return out;
 }
 
-// A start that plans first goes by its plan phase: it needs no Mac or
-// simulator, and a plan-only one that no machine can take starts here
+// A start that plans first goes by its plan phase: it needs no simulator, and a plan-only one that no machine can take starts here
 // as ever (it never waits on load).
 const plansFirst = (r: QueueRow) => !!(r.plan || r.plan_only);
 
+// Planning needs no simulator or Xcode, and a need read from the files or the
+// brief doesn't hold it. Only an explicit Mac pin does: the work is Mac-only
+// (often because the other machine can't reach what it touches).
+const planNeeds = (r: QueueRow, needs: Need[]): Need[] => {
+  const project = getProject(r.project_id);
+  return project &&
+    needs.includes("mac") &&
+    pinnedToMac(r.machine_needs, expandHome(project.working_directory))
+    ? ["mac"]
+    : [];
+};
+
 // Marks each start the home machine's load rules out as remote and returns
 // where it goes. "stale": the line moved while the machines were asked, so
 // this look is over, and the one a change during it asks for sees the line
@@ -143,7 +155,7 @@ export async function placeCandidates(
       asked(c),
       home,
       options,
-      plan ? [] : (needsOf.get(c.id) ?? []),
+      plan ? planNeeds(r, needsOf.get(c.id) ?? []) : (needsOf.get(c.id) ?? []),
       now
     );
     if (!spot) continue;

package/lib/welcome-url.ts

@@ -1,5 +1,5 @@
 // The welcome has its own address: `/?welcome=<step>`, beside `?settings=`
-// and `?session=`. `/welcome` redirects here.
+// and a session's `/s/<name>-<id8>`. `/welcome` redirects here.
 
 export const WELCOME_PARAM = "welcome";
 

package/next.config.ts

@@ -13,6 +13,10 @@ const nextConfig: NextConfig = {
   experimental: {
     agentUpgrade: false,
   },
+  // A session's readable address (lib/session-url) is the same one page.
+  async rewrites() {
+    return { beforeFiles: [{ source: "/s/:ref", destination: "/" }] };
+  },
   turbopack: {
     root: resolve(import.meta.dirname),
   },

package/package.json

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

package/stores/chatJump.ts

@@ -4,7 +4,11 @@ import { bookmarksUiActions } from "@/stores/bookmarksUi";
 // Opens a chat by its address, then takes it to one message (bookmarks and
 // search both end here). The chat takes the jump once it is on screen.
 export function openChatAt(sessionId: string, itemId: string): void {
-  window.history.pushState(null, "", hrefWithSession(location.href, sessionId));
+  window.history.pushState(
+    null,
+    "",
+    hrefWithSession(location.href, { id: sessionId })
+  );
   window.dispatchEvent(new PopStateEvent("popstate"));
   bookmarksUiActions.jump(sessionId, itemId);
 }