@crievo/omni 0.1.6 → 0.1.8

package/omnivideo.config.example.json

@@ -293,6 +293,7 @@
     "omnichat": false,
     "metrics": false,
     "schedule": false,
+    "user": false,
     "studio": false,
     "studio_url": ""
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crievo/omni",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "OmniVideo no seu computador: o CLI omni, o studio local e as ferramentas do pipeline.",
   "type": "module",
   "bin": {

package/reference/cloud.md

@@ -39,7 +39,7 @@ and the studio talk to the Worker with `OMNICHAT_CLOUD_SECRET` (the Worker's `SY
   back if it stops, log in `.runner/studio.log`; `service restart` after a `git pull`). Setup:
   `node cloud/studio/setup-auth.mjs` (tables and secrets), then `npx wrangler deploy` in `cloud/studio`.
   Every write that goes through to the Mac is logged (email, method, path, status; the last 2000, at
-  `<studio>/runner/audit`) and limited to 120 a minute per user (429 beyond it); a runner and a hub on
+  Configurações → Agente de IA, from `<studio>/session/audit`) and limited to 120 a minute per user (429 beyond it); a runner and a hub on
   different protocol numbers refuse each other and say which side is old.
   Protocol in `tools/lib/channel.mjs`, plan in `docs/specs/phase-1-split-api.md`.
 - **Each job has an off switch in the database** (`settings`: `active`, `metrics_active`,
@@ -55,6 +55,20 @@ and the studio talk to the Worker with `OMNICHAT_CLOUD_SECRET` (the Worker's `SY
 
 Turning back: the flag to `false` and the push again (the cloud stops), and the local agent on.
 
+## The per-user cloud (Phase 3, in progress)
+
+The jobs above are moving from the shared `omnichat` Worker into one Durable Object per user, `UserCloud` in the studio
+Worker (`cloud/studio/src/cloud-*.mjs`), with their own config, secrets, webhook (`/hook/<cloudId>`), media
+(`u/<cloudId>/` in R2) and one alarm in place of the crons and the KV gate. Step 2 (the jobs inside the object) is built and
+tested but not deployed or used by a machine yet; the `omnichat` Worker above still does the real work until steps 3–4.
+Routes, flags and what differs from the sketch: `docs/specs/phase-3-per-user-cloud.md`, "Step 2, as built".
+
+On the machine, `cloud.user: true` (with `cloud.studio_url`, signed in with the Omni login) points the omnichat, the
+Instagram account and the metrics at that cloud instead of the Worker; publishing (the schedule, the media published
+now, the YouTube/TikTok credentials) stays on the Worker until the last step. Off by default: turning it on points the
+CLIs at an empty cloud, so see "Step 3, as built so far" in the spec for the order (push first, and the Worker stops
+answering before the new cloud starts).
+
 ## Free plans and their limits
 
 - **Workers Free:** 10 ms of CPU and 50 subrequests per run. That is why a cloud pass sends at most 5 DMs

package/reference/learnings.md

@@ -814,3 +814,10 @@ these voices).
 - **Symptom:** none yet; found reading the queue for a Windows port.
 - **Cause:** on Windows, Python's `os.kill(pid, sig)` treats `sig == 0` as `CTRL_C_EVENT` and sends it to the process group of `pid`; any other number is a `TerminateProcess`. The Node `process.kill(pid, 0)` is a real probe on both systems.
 - **Fixed:** `tools/job_queue.py` asks the kernel (`OpenProcess` + `GetExitCodeProcess`, `STILL_ACTIVE`) on Windows and keeps `os.kill` plus the `ps` zombie check elsewhere. Also on Windows: `select()` works on sockets only (the guardian reads the Node pipe in a thread), an atomic replace fails while a reader has the file open (retry), and a text file is written in the code page unless `encoding="utf-8"` says otherwise.
+
+## A turn's `total_cost_usd` is the session's running total, not the turn's (18/10/2026)
+
+- **Symptom:** the studio's session list showed US$ 220,93 for the Grok video, whose last turn closed at US$ 53,79. Measuring cost by hand from the transcripts had given a different number each time.
+- **Cause:** `claude -p --resume` keeps adding to the conversation's totals. The `result` of turn N carries `total_cost_usd`, `modelUsage[].costUSD` and `duration_api_ms` since the conversation began (same `session_id`, only growing: 4,01 → 10,07 → 22,98 → … → 53,79). Summing the turns' costs counts the early turns again and again. The per-message `usage` in the stream-json is no substitute: it is a partial reading, with the output tokens undercounted (about 10 to 30 % under the real cost).
+- **Fixed:** `tools/lib/cost.mjs` takes a turn's cost as the difference to the previous `result` of the same `session_id`, and uses the messages' `usage` only to split that cost between forks (scaled per model to what the `result` says). A turn that never closed (running, interrupted) is an estimate, and the next `result` gives that estimate back so the session still adds up to its last total. `summarizeSession` counts each conversation once, by its last total. Rule: to measure what an agent spent, run `node tools/cost.mjs`; do not add up `result` costs by hand, and count messages by `message.id`, never by transcript line.
+

package/reference/studio.md

@@ -594,6 +594,7 @@ comes, that it be the studio's own.
 | `POST /api/videos/<slug>/sound` | `{ places, bed }` → `sound` on the beats, `transition.sound` and `bed` in `scenes.json` (validated; defaults are dropped) |
 | `POST /api/videos/<slug>/sound/reassemble` | runs `assemble.mjs` (waits for its turn in the queue) |
 | `GET /kit/<name>` | MP3 from the global kit (`kit/sfx/`), for the waveform |
+| `GET /api/cost` | `tools/lib/cost.mjs`: what the Claude sessions spent, by video, stage, fork, model and day (`?days=N`); reads `.sessions/`, cache in `.cost/` |
 | `GET /api/usage` | `tools/usage.py summary --json`: Fish balance, Cartesia quota, usage per video and latest generations (only reads the local log) |
 | `POST /api/usage/refresh` | the same with `--live`: asks the platforms now and writes the reading to `.usage/` |
 | `GET /api/analytics` | `tools/analysis.mjs context` (account, medians at the current reading and at the 24 h and 72 h milestones, also per thousand views, the channel's hour-by-hour `progression` and the `publications` in it, the playbook's `before` range, each Reel with metrics, strategy and hook, the agent) plus the text of the latest channel analysis |

package/studio/api/app.ts

@@ -28,6 +28,7 @@ import { onboarding } from "./routes/onboarding";
 import { publish } from "./routes/publish";
 import { queue } from "./routes/queue";
 import { references } from "./routes/references";
+import { me } from "./routes/me";
 import { runner } from "./routes/runner";
 import { schedule } from "./routes/schedule";
 import { services } from "./routes/services";
@@ -36,6 +37,7 @@ import { settings } from "./routes/settings";
 import { sound, SOUND_UPLOAD_PATH } from "./routes/sound";
 import { thumbnail } from "./routes/thumbnail";
 import { usage } from "./routes/usage";
+import { cost } from "./routes/cost";
 import { videos } from "./routes/videos";
 import { voices } from "./routes/voices";
 
@@ -63,8 +65,10 @@ export function createApp({ port }: AppOptions) {
     .route("/", references)
     .route("/", queue)
     .route("/", runner)
+    .route("/", me)
     .route("/", services)
     .route("/", usage)
+    .route("/", cost)
     .route("/", analytics)
     .route("/", settings)
     .route("/", clone)

package/studio/api/routes/cost.ts

@@ -0,0 +1,13 @@
+/* Agent cost (settings Uso e custo): what the Claude sessions spent, by video, stage and model. */
+
+import { router } from "../lib/hono";
+import { shaped } from "../lib/result";
+import { query } from "../lib/validate";
+import { getCost } from "../services/cost";
+import { costQuery } from "../../shared/schemas/cost";
+import type { AgentCost } from "../../shared/types/api";
+
+export const cost = router().get("/cost", query(costQuery), async c => {
+  const days = Number(c.req.valid("query").days) || null;
+  return c.json(shaped<AgentCost>(await getCost(days)));
+});

package/studio/api/routes/me.ts

@@ -0,0 +1,8 @@
+/* Who is using the studio (services/me.ts), for the menu's user card at 127.0.0.1, and its sign-out. */
+
+import { router } from "../lib/hono";
+import { getMe, signOutOmni } from "../services/me";
+
+export const me = router()
+  .get("/me", async c => c.json({ me: await getMe() }))
+  .post("/me/logout", async c => c.json(await signOutOmni()));

package/studio/api/services/agent-tools.ts

@@ -853,7 +853,7 @@ const SCHEDULE_STATE: Record<string, string> = {
   scheduled: "agendado",
   publishing: "publicando agora",
   failed: "falhou",
-  missed: "perdido (o Mac estava desligado)",
+  missed: "perdido (a máquina estava desligada)",
 };
 
 export async function toolSchedule(from?: string, to?: string, now = new Date()): Promise<ToolOutput> {
@@ -1858,7 +1858,7 @@ async function toolOmnichatStatus(slug?: string, content?: "video" | "carousel")
       account: st.account?.ready ? { username: st.account.username ?? null } : { problem: st.account?.reason ?? null },
       comments_permission: st.comments?.ready ?? null,
       /* who answers the comments: the cloud Worker, or this Mac's launchd agent */
-      answered_by: st.agent?.cloud?.ready ? "nuvem" : st.agent?.loaded ? "este Mac" : "ninguém (agente parado)",
+      answered_by: st.agent?.cloud?.ready ? "nuvem" : st.agent?.loaded ? "esta máquina" : "ninguém (agente parado)",
       pause: st.pause,
       rules: (st.rules ?? []).map((r: any) => ({
         content: r.type,

package/studio/api/services/cost.ts

@@ -0,0 +1,22 @@
+/* What the agents spent on the videos. The accounting lives in tools/lib/cost.mjs, which
+   tools/cost.mjs (the terminal) also uses; the studio only shows what it returns.
+   A finished turn is cached on disk, but the open ones are read again, so the answer is kept for
+   a few seconds: the UI reloads on every queue change. */
+
+import { readTurns, summarize } from "../../../tools/lib/cost.mjs";
+
+const cached = new Map<string, { at: number; data: Promise<unknown> }>();
+
+export function getCost(days: number | null) {
+  const key = String(days ?? "all");
+  const hit = cached.get(key);
+  if (hit && Date.now() - hit.at < 5000) return hit.data;
+  const data = readTurns({ since: days ? Date.now() - days * 86_400_000 : null }).then(rows => ({
+    days,
+    ...summarize(rows),
+  }));
+  cached.set(key, { at: Date.now(), data });
+  /* a failed reading is not kept */
+  data.catch(() => cached.delete(key));
+  return data;
+}

package/studio/api/services/me.ts

@@ -0,0 +1,67 @@
+/* Who is using the studio, for the menu's user card (GET /api/me). The hosted page doesn't ask this: the Worker
+   answers /session/me from the signed-in session, even while this computer is away. Here, at 127.0.0.1, it is
+   the account signed in to Omni on this computer (the plugin's login: the Worker's /account), else the Claude
+   Code account that runs the agent (its name and email, read from its own files), which also fills in a name the
+   Omni account doesn't carry yet. Without either, nobody:
+   the card hides. Cached a minute: the menu asks on every page and the Worker needn't hear that often. */
+
+import { accountsOf, loginOf } from "../../../tools/lib/agents.mjs";
+import { accessToken, logout, readTokens } from "../../../tools/lib/oauth-client.mjs";
+import { cloudSettings } from "../../../tools/platforms.mjs";
+import type { Me } from "../../shared/types/api";
+import { readConfig } from "./settings";
+
+const TTL_MS = 60_000;
+let cached: { at: number; me: Me | null } | null = null;
+
+/* the Omni account of this computer: its login's token trades for the account at the Worker */
+async function omniAccount(): Promise<Me | null> {
+  const url = cloudSettings().studio.url;
+  if (!url) return null;
+  try {
+    const token = await accessToken(url);
+    if (!token) return null;
+    const r = await fetch(`${url}/account`, {
+      headers: { authorization: `Bearer ${token}` },
+      signal: AbortSignal.timeout(4000),
+    });
+    if (!r.ok) return null;
+    const a = (await r.json()) as { email?: string | null; name?: string | null; image?: string | null };
+    return a.email ? { name: a.name ?? null, email: a.email, image: a.image ?? null, source: "omni" } : null;
+  } catch {
+    return null;
+  }
+}
+
+/* the Claude Code account the agent runs on */
+function claudeAccount(): Me | null {
+  for (const a of accountsOf(readConfig() ?? {}) as { provider: string }[]) {
+    if (a.provider !== "claude") continue;
+    const login = loginOf(a) as { email: string | null; name?: string | null } | null;
+    if (login?.email) return { name: login.name ?? null, email: login.email, image: null, source: "claude" };
+  }
+  return null;
+}
+
+export async function getMe(now = Date.now()): Promise<Me | null> {
+  if (cached && now - cached.at < TTL_MS) return cached.me;
+  const claude = claudeAccount();
+  const omni = await omniAccount();
+  /* the Worker may not know the name yet: the Claude Code account of the same email does */
+  const me = omni ? { ...omni, name: omni.name ?? (claude?.email === omni.email ? claude.name : null) } : claude;
+  cached = { at: now, me };
+  return me;
+}
+
+/* Sair da conta Omni deste computador: the same as `omni logout`. The Worker is told to end this computer's login
+   and the tokens here are forgotten; the card then falls back to the Claude Code account, or hides. */
+export async function signOutOmni(): Promise<{ ok: boolean; output?: string; error?: string }> {
+  const url = cloudSettings().studio.url;
+  if (!url || !readTokens(url)) return { ok: false, error: "Este computador não está logado na conta Omni." };
+  const confirmed = await logout(url);
+  cached = null;
+  return {
+    ok: true,
+    output: confirmed ? "Saiu da conta Omni." : "Saiu da conta Omni aqui; o studio hospedado não confirmou.",
+  };
+}

package/studio/api/services/sessions.ts

@@ -336,7 +336,13 @@ function stateOf(r: SessionRecord): { state: SessionState; result: TurnResult |
 export function summarizeSession(r: SessionRecord) {
   const { state, result, now } = stateOf(r);
   const t = r.turns.at(-1);
-  const costs = r.turns.map(x => turnInfo(r, x).result?.cost ?? 0);
+  /* a turn's `cost` is the conversation's running total (--resume keeps adding to it), so a
+     conversation counts once, by its last total; a handoff to another account is a new one */
+  const running = new Map<string, number>();
+  for (const x of r.turns) {
+    const cost = turnInfo(r, x).result?.cost;
+    if (cost != null) running.set(x.engine_id ?? r.id, Math.max(running.get(x.engine_id ?? r.id) ?? 0, cost));
+  }
   const account = t ? accountOfTurn(r, t) : null;
   let activity = Date.parse(r.created_at);
   try {
@@ -355,7 +361,7 @@ export function summarizeSession(r: SessionRecord) {
     turns: r.turns.length,
     turn: t ? { n: t.n, origin: t.origin, prompt: t.prompt, started_at: t.started_at, pid: t.pid, result } : null,
     now,
-    total_cost: +costs.reduce((a, b) => a + b, 0).toFixed(4),
+    total_cost: +[...running.values()].reduce((a, b) => a + b, 0).toFixed(4),
     agent: t ? { provider: providerOf(t), account: account?.id ?? null, label: account?.label ?? null } : null,
   };
 }

package/studio/runner/runner.ts

@@ -25,6 +25,9 @@ const DEAD_MS = 75_000;
 const KEY_CHECK_MS = 30_000;
 /* a refused key pairs again by itself at most this often (the approval page opens on this Mac) */
 const PAIR_EVERY_MS = 60 * 60_000;
+/* with no login (never entered, signed out, or disconnected at the studio) the approval page opens on this computer by
+   itself, at most this often: it asks for a click, and someone who closed it didn't want it every hour */
+const LOGIN_EVERY_MS = 6 * 60 * 60_000;
 
 export type RunnerOptions = {
   /** the hosted studio, https://… */
@@ -42,6 +45,18 @@ export type RunnerOptions = {
   /** pairs this Mac again (opens the approval page, waits, saves the new key): the key, or null. Called when
    *  the cloud refuses the key, never after a "Desconectar", which is the user's own decision */
   pair?: () => Promise<string | null>;
+  /** signs this computer in again: opens the approval page in the browser and waits for the user to approve
+   *  (tools/lib/oauth-client.mjs login). Called when there is no usable login, so nobody has to open a terminal or
+   *  Claude Code to get back in; the user only approves */
+  login?: () => Promise<void>;
+  /** the hub says this machine and the hosted studio speak different protocols (UPGRADE). Which side is old isn't
+   *  in the close reason, so whoever answers this looks (tools/lib/self-update.mjs: is there a newer version of
+   *  the CLI?) and updates this machine when it is the one behind. Called on every retry, a minute apart. */
+  onOutdated?: () => void | Promise<void>;
+  /** the waits, in ms; the tests shorten them */
+  keyCheckMs?: number;
+  loginEveryMs?: number;
+  protocolRetryMs?: number;
 };
 
 /** Range on a media response: 206 from a Blob slice, 416 out of bounds; the rest as it is. */
@@ -107,6 +122,10 @@ export function startRunner(o: RunnerOptions) {
   let hinted = false;
   let pairing = false;
   let pairedAt = 0;
+  const keyCheckMs = o.keyCheckMs ?? KEY_CHECK_MS;
+  const loginEveryMs = o.loginEveryMs ?? LOGIN_EVERY_MS;
+  let signingIn = false;
+  let signedInAt = 0;
 
   const serve = async (request: Request) => withRange(request, await o.handle(asLocal(request, o.port)));
 
@@ -114,9 +133,10 @@ export function startRunner(o: RunnerOptions) {
     /* an unreachable studio while refreshing says nothing about the login: try again later */
     const token = await Promise.resolve(o.token()).catch(() => "");
     if (!token || token === revoked) {
-      if (!hinted) log("aviso: este Mac não está pareado com o studio hospedado: npx -y @crievo/omni login");
+      if (!hinted) log("aviso: esta máquina não está conectada ao studio hospedado");
       hinted = true;
-      timer = setTimeout(connect, KEY_CHECK_MS);
+      void signIn();
+      timer = setTimeout(connect, keyCheckMs);
       return;
     }
     hinted = false;
@@ -171,17 +191,20 @@ export function startRunner(o: RunnerOptions) {
       /* the key was deleted at /runner: wait for a new pairing instead of knocking with the old key */
       if (e.code === REVOKED) {
         revoked = token;
-        log("aviso: este Mac foi desconectado do studio hospedado; para voltar: node tools/runner.mjs login");
+        log("aviso: esta máquina foi desconectada do studio hospedado");
         hinted = true;
-        timer = setTimeout(connect, KEY_CHECK_MS);
+        /* the next look finds no login and opens the approval page (once): the user can approve or refuse it */
+        timer = setTimeout(connect, keyCheckMs);
         return;
       }
       /* the hub and this Mac speak different protocols: say which side is old, and look again in a minute
          (the studio may be redeployed, or this Mac updated, without a restart) */
       if (e.code === UPGRADE) {
-        if (!warned) log(`aviso: este Mac e o studio hospedado não se entendem (${e.reason}); tento de novo em 1 min`);
+        if (!warned)
+          log(`aviso: esta máquina e o studio hospedado não se entendem (${e.reason}); tento de novo em 1 min`);
         warned = true;
-        timer = setTimeout(connect, 60_000);
+        void Promise.resolve(o.onOutdated?.()).catch(() => {});
+        timer = setTimeout(connect, o.protocolRetryMs ?? 60_000);
         return;
       }
       if (was || !warned) {
@@ -200,6 +223,30 @@ export function startRunner(o: RunnerOptions) {
       /* onclose follows */
     };
   };
+  /* No usable login: opens the approval page on this computer and waits for the user to approve, then connects with
+     the login it stored. At most once in a while, and never twice at the same time. */
+  const signIn = async () => {
+    if (!o.login || stopped || signingIn) return;
+    if (signedInAt && Date.now() - signedInAt < loginEveryMs) return;
+    signingIn = true;
+    signedInAt = Date.now();
+    log("aviso: abri a página de aprovação no navegador desta máquina: aprove para reconectar");
+    try {
+      await o.login();
+      log("cloud: login refeito");
+      delay = 1000;
+      hinted = false;
+      revoked = "";
+      if (!stopped) {
+        if (timer) clearTimeout(timer);
+        void connect();
+      }
+    } catch (e) {
+      log(`aviso: o login não terminou (${(e as Error).message})`);
+    } finally {
+      signingIn = false;
+    }
+  };
   /* The key was refused (the login was redone, the key went missing in the cloud…): pair again, which opens
      the approval page on this Mac, and connect with the new key. True when it took over the retry. */
   const repair = async (token: string): Promise<boolean> => {
@@ -208,13 +255,13 @@ export function startRunner(o: RunnerOptions) {
     if (k.valid !== false) return false;
     revoked = token;
     if (Date.now() - pairedAt < PAIR_EVERY_MS) {
-      timer = setTimeout(connect, KEY_CHECK_MS);
+      timer = setTimeout(connect, keyCheckMs);
       return true;
     }
     pairing = true;
     pairedAt = Date.now();
     log(
-      "aviso: o studio hospedado recusou a chave deste Mac; abri a página de aprovação no navegador: aprove para reconectar",
+      "aviso: o studio hospedado recusou a chave desta máquina; abri a página de aprovação no navegador: aprove para reconectar",
     );
     const key = await o.pair!().catch(e => {
       log(
@@ -225,11 +272,11 @@ export function startRunner(o: RunnerOptions) {
     pairing = false;
     if (stopped) return true;
     if (key) {
-      log("cloud: Mac pareado de novo");
+      log("cloud: máquina pareada de novo");
       delay = 1000;
       hinted = false;
       void connect();
-    } else timer = setTimeout(connect, KEY_CHECK_MS);
+    } else timer = setTimeout(connect, keyCheckMs);
     return true;
   };
 

package/studio/shared/omni-screens.ts

@@ -39,7 +39,7 @@ export const SCREENS: Record<ScreenId, { label: string; path: string }> = {
   /* where a content's Omnichat is set up, always: /omnichat/video/<slug> (or carousel) */
   omnichat_rule: { label: "Omnichat de um conteúdo", path: "/omnichat/$kind/$id" },
   settings: { label: "Configurações", path: "/settings" },
-  usage: { label: "Uso das vozes", path: "/usage" },
+  usage: { label: "Uso e custo", path: "/usage" },
   omni_measures: { label: "Medições do Omni", path: "/agent" },
   getting_started: { label: "Primeiros passos", path: "/getting-started" },
 };

package/studio/shared/schemas/cost.ts

@@ -0,0 +1,10 @@
+/* Agent cost (settings Uso e custo): ?days=N limits the window, none = everything recorded. */
+
+import { z } from "zod";
+
+export const costQuery = z.object({
+  days: z
+    .string()
+    .regex(/^\d{1,4}$/)
+    .optional(),
+});

package/studio/shared/types/api.ts

@@ -939,6 +939,44 @@ export type UsageData = {
 
 export type Usage = UsageData | { error: string };
 
+/* what the agents spent (tools/lib/cost.mjs): the Claude turns in .sessions/, by video, stage and model */
+export type AgentCostVideo = {
+  video: string;
+  type: string;
+  total: number;
+  turns: number;
+  first: string;
+  last: string;
+  stages: Record<string, number>;
+  models: Record<string, number>;
+};
+export type AgentCostFork = {
+  video: string;
+  session: string;
+  turn: number;
+  stage: string;
+  label: string;
+  cost: number;
+  messages: number;
+};
+export type AgentCost = {
+  /* the window in days; null = everything recorded */
+  days: number | null;
+  total: number;
+  turns: number;
+  sessions: number;
+  /* turns that never closed: their cost is an estimate */
+  partial: number;
+  /* turns with no dollar cost (Codex) */
+  unmeasured: number;
+  by_kind: Record<string, number>;
+  by_stage: Record<string, number>;
+  by_model: Record<string, number>;
+  by_day: { day: string; cost: number }[];
+  by_video: AgentCostVideo[];
+  top_forks: AgentCostFork[];
+};
+
 /* --- settings ---------------------------------------------------------------------------- */
 export type KeyStatus = { name: string; masked: string | null; in_env: boolean };
 
@@ -1184,6 +1222,42 @@ export type RunnerProblem =
   | { reason: "protocol"; at: string; side: "mac" | "cloud"; host?: string }
   | { reason: "revoked"; at: string; name?: string };
 
+/* the first-time setup the CLI reports to the user's cloud while the studio isn't connected yet
+   (tools/lib/setup-progress.mjs; read from GET /api/cloud/config, key `setup`) */
+export type SetupStepState = "pending" | "running" | "done" | "error";
+export type SetupStep = { id: string; label: string; detail: string; state: SetupStepState; error?: string };
+export type SetupRecord = {
+  v: 1;
+  state: "running" | "done" | "error";
+  device: string;
+  started_at: number;
+  updated_at: number;
+  steps: SetupStep[];
+  /* the last time the process waiting for a retry looked (the page offers "Tentar de novo" while it is recent) and the
+     id of the last retry request it answered */
+  watching_at?: number;
+  handled?: string;
+};
+/* what the page writes to ask for a retry (`setup_retry` of the cloud config): a step id, or "all" */
+export type SetupRetryRequest = { id: string; step: string; at: number };
+
+/* who is using the studio: the menu's user card (GET /api/me here; the Worker's /session/me when hosted).
+   `source` is where a local studio found them: the Omni login, or the Claude Code account */
+export type Me = { name: string | null; email: string; image: string | null; source: "omni" | "claude" | "session" };
+
+/* the computers signed in to the hosted studio, and the actions that went through to them
+   (the Worker's /session/computers and /session/audit: cloud/studio/src/account-routes.mjs) */
+export type Computer = {
+  id: string;
+  name: string;
+  /* "login": entered with the plugin; "key": the old pairing key (tools/runner.mjs) */
+  kind: "login" | "key";
+  created_at: number;
+  last_seen: number | null;
+  online: boolean;
+};
+export type AuditEntry = { at: number; who: string; method: string; path: string; status: number; ms: number };
+
 /* --- the admin panel (GET /api/admin) ------------------------------------------------------------ */
 export type OmniAdminSettings = {
   enabled: boolean;

package/studio/studio.ts

@@ -35,7 +35,9 @@ import { resumeAfterApproval, watchDeadline } from "./api/services/approval";
 import { startRunner } from "./runner/runner";
 import { cloudSettings, env, writeEnv } from "../tools/platforms.mjs";
 import { checkKey, finishPairing, startPairing } from "../tools/lib/pairing.mjs";
-import { ACCESS_PREFIX, accessToken } from "../tools/lib/oauth-client.mjs";
+import { ACCESS_PREFIX, accessToken, login, readTokens } from "../tools/lib/oauth-client.mjs";
+import { createSelfUpdater } from "../tools/lib/self-update.mjs";
+import { setupRunning } from "../tools/lib/setup-progress.mjs";
 import { openUrl } from "../tools/lib/platform.mjs";
 
 const args = process.argv.slice(2);
@@ -146,6 +148,29 @@ if (args.includes("--runner") || (hosted.on && option("port") === undefined)) {
     };
     /* only a Phase 1 key is repaired by pairing; an OAuth login refreshes itself or asks for omni login */
     const check = async (t: string) => (t.startsWith(ACCESS_PREFIX) ? { valid: null } : checkKey(url, t));
-    startRunner({ url, token, port, handle, checkKey: check, pair });
+    /* no usable login (never entered, signed out, disconnected): the approval page opens on this computer by itself */
+    const signIn = async () => {
+      /* the plugin's hook may be asking for this very login: wait for it instead of opening a second page */
+      for (let i = 0; i < 144 && setupRunning(); i++) await new Promise(r => setTimeout(r, 5000));
+      if (readTokens(url)) return;
+      await login(url, { deviceName: hostname().replace(/\.local$/, "") });
+    };
+    /* a machine behind the hosted studio updates itself: the hub closes the socket with UPGRADE, and this asks npm
+       whether a newer CLI exists (tools/lib/self-update.mjs); never on a checkout, once an hour */
+    const update = createSelfUpdater({
+      log: line => console.log(line),
+      busy: setupRunning,
+      loggedIn: () => !!readTokens(url),
+    });
+    startRunner({
+      url,
+      token,
+      port,
+      handle,
+      checkKey: check,
+      pair,
+      login: signIn,
+      onOutdated: async () => void (await update()),
+    });
   }
 }

package/studio/web/components/AppShell.tsx

@@ -1,10 +1,14 @@
 /* The root route component: the top banners, the menu, the page (<Outlet/>) inside the scrolling
-   .content, the lightbox, the approval notice, Omni, the toasts and, over everything, the screen for a studio that lost its connection, the voice agent (its panel opens from the sidebar button). */
+   .content, the lightbox, the approval notice, Omni (the voice agent, its panel opens from the sidebar button) and
+   the toasts. While the studio isn't connected, its screen takes the page's place inside .content, with the menu
+   still there; the page stays mounted underneath, hidden, so what it held is back when the studio is. Settings →
+   Agente de IA stays reachable: the computers and the actions there come from the Worker, not from the studio. */
 
 import { useEffect, useRef } from "react";
 import { Outlet, useLocation, useMatchRoute } from "@tanstack/react-router";
 import { useMenuCollapsed } from "../hooks/useMenuCollapsed";
 import { useMissingSetupSteps } from "../hooks/useMissingSetupSteps";
+import { useRunner } from "../hooks/useRunner";
 import { ApprovalNotice } from "./ApprovalNotice";
 import { TopBanners } from "./TopBanners";
 import { Lightbox } from "./Lightbox";
@@ -32,6 +36,9 @@ export function AppShell() {
   const [collapsed, toggleMenu] = useMenuCollapsed();
   const showGettingStarted = location.pathname === "/getting-started" || !!missing?.length;
   const withSidebar = !!matchRoute({ to: "/settings", fuzzy: true }) || !!matchRoute({ to: "/usage" });
+  const { online } = useRunner();
+  const onAgentSettings = !!matchRoute({ to: "/settings/$category", params: { category: "agent" } });
+  const offlineScreen = online === false && !onAgentSettings;
 
   /* the content panel scrolls, not the window: back to the top on every page change */
   const pageKey = pageKeyOf(location.pathname, location.searchStr);
@@ -51,15 +58,16 @@ export function AppShell() {
           showGettingStarted={showGettingStarted}
         />
         <div className="content" ref={content}>
-          <main className={withSidebar ? "with-sidebar" : ""}>
+          <main className={withSidebar ? "with-sidebar" : ""} hidden={offlineScreen}>
             <Outlet />
           </main>
+          {/* always mounted: it is what sends the first time on to Primeiros passos once the studio answers */}
+          <StudioOffline suppressed={onAgentSettings} />
         </div>
       </div>
       <Lightbox />
       <ApprovalNotice />
       <OmniWidget menuCollapsed={collapsed} />
-      <StudioOffline />
       <Toaster />
     </>
   );