samagotchi 0.102.0 → 0.103.0

data/lib/samagotchi/web/public/working_set_view.js

@@ -5,10 +5,19 @@
 // and the step tags' jump to a call. The rail is working_set_rail.js's; the
 // rules are working_set.js's.
 //
-// Steering (P3a: drop / undrop): the list's rows and groups post
-// `/working-set drop|undrop KEY…` lines (+sendLine+, the session command
-// route). Between turns one runs at once: its command_ran re-reads the
-// conversation and the re-emitted set strikes the item `dropped`. While a
+// Steering (drop / undrop, pin / unpin, + add): the list's rows and groups post
+// `/working-set drop|undrop|pin|unpin|add KEY…` lines (+sendLine+, the session
+// command route). The list's foot (the sheet's last row) adds what the user
+// types (a path, memory:NAME or a URL); a stale or forgotten row offers
+// refresh (an add of it). An add is pending until the next turn sends its
+// note: the server's snapshot lists it (adds) between turns, a queued line
+// mid-turn; an added item the set doesn't hold yet is a `+ name` row with
+// `reads next turn` and an undo (unadd). Between turns one runs at once: its command_ran re-reads the
+// conversation and the re-emitted set strikes the item `dropped` (or marks
+// it pinned). A row offers pin only when the session's strategy has the
+// forget layer (forgetOn: pins guard against the model's forget); a pinned
+// row shows its 📌 and unpin under any strategy, since its drop waits for
+// the unpin. While a
 // turn runs it is queued: its command_queued (waits: "turn_end"; any
 // client's, and the snapshot's replay after a reload) makes it pending, a
 // dashed-warn row with a pill and an undo (the inverse line, queued after
@@ -32,8 +41,9 @@ import { html, nothing, render, svg } from "./vendor/lit-html.js";
 import { createChipPopover } from "./chip_popover.js";
 import { showRow } from "./refs.js";
 import {
-  BUDGETS, dropRefusal, fold, footprint, footprintText, GLYPHS, INVERSE, isFresh, itemsOfTurn, labelText, labelTitle, newerSnapshot,
-  opsText, overlay, parseSteerLine, pendingSteers, sessionItems, steerId, steerLine, stepRange, stepTag, tokensText,
+  addedItems, addLine, BUDGETS, dropRefusal, fold, footprint, footprintText, forgetOn, GLYPHS, INVERSE, isFresh, itemsOfTurn, labelText,
+  labelTitle, newerSnapshot, opsText, overlay, parseSteerLine, pendingSteers, pinnable, refreshable, serverAddIds, sessionItems, STEER_OPS,
+  steerId, steerLine, stepRange, stepTag, tokensText, undroppable,
 } from "./working_set.js";
 
 // The popover's files fold to this many lines (groups open in place, one at
@@ -194,38 +204,69 @@ export function createWorkingSet({ historyEl, stageRoot = () => null, state, ses
       if (opening) fetchServer();
     },
     onClose: () => { openGroup = null; onChange(); },
+    // The foot's + add (the popover's submit): one KEY as typed (quoted
+    // when it has spaces).
+    onSubmit: (form) => {
+      if (!form?.matches?.(".ws-add")) return;
+      const input = form.querySelector(".ws-add-in");
+      const line = sendLine && addLine(input?.value);
+      if (!line) return;
+      input.value = "";
+      Promise.resolve(sendLine(line)).catch(() => {});
+    },
   });
 
-  const pending = () => pendingSteers([...queued.values()]);
+  // The pending ops: the server's adds (made between turns), then the
+  // queued lines.
+  const pending = () => pendingSteers([...queued.values()], state().dir, serverAddIds(server));
+  // The pending adds the set doesn't hold yet, as rows.
+  const adding = (pend = pending()) => addedItems(pend, sessionSet().items, server, state().dir);
 
   // A steer button: +op+ on +items+ ("undo" sends the inverse of a pending op).
   function actButton(op, items, { label = op, title = "", disabled = false } = {}) {
-    const ids = items.map(steerId).join(" ");
+    // JSON: an id may hold spaces (a file under "my notes/").
+    const ids = JSON.stringify(items.map(steerId));
     return html`<button type="button" class=${`ws-act-b ${op}`} data-ws="steer" data-op=${op} data-ids=${ids} title=${title} ?disabled=${disabled}>${label}</button>`;
   }
 
+  // A pending op's pill.
+  const PILLS = { drop: "drops next turn", undrop: "back next turn", pin: "applies next turn", unpin: "applies next turn",
+    add: "reads next turn" };
+
   // What a row offers: a pending op's pill and undo, an undrop, a drop (or
-  // why not); nothing for an item no op applies to.
-  function rowActions(item, pend) {
+  // why not), a pin or an unpin; nothing for an item no op applies to.
+  function rowActions(item, pend, forget) {
     if (!sendLine) return { pill: nothing, buttons: nothing };
-    const op = pend.get(steerId(item));
+    let op = pend.get(steerId(item));
+    // A drop queued for a pinned item: the worker refuses it (unpin it
+    // first), so it isn't pending; the row offers its greyed drop.
+    if (op === "drop" && item.pinned) op = undefined;
     if (op) {
-      const pill = html`<span class="ws-pend" title="applies at the next turn's start">${op === "drop" ? "drops next turn" : "back next turn"}</span>`;
+      const when = op === "add" ? "the next turn's note asks the model to read it first" : "applies at the next turn's start";
+      const pill = html`<span class="ws-pend" title=${when}>${PILLS[op]}</span>`;
       return { pill, buttons: actButton(INVERSE[op], [item], { label: "undo", title: `take back the queued ${op}` }) };
     }
-    if (item.state === "dropped") {
-      return { pill: nothing, buttons: actButton("undrop", [item], { title: "send it whole again from the next request (a cache break)" }) };
-    }
+    const undrop = actButton("undrop", [item], { title: "send it whole again from the next request (a cache break)" });
+    // Dropped, or a drop on some reads with nothing else of it sent (the
+    // model's layers stubbed the rest): undrop is all it offers.
+    if (item.state === "dropped" || (undroppable(item) && item.state === "forgotten")) return { pill: nothing, buttons: undrop };
+    const buttons = [];
     const why = dropRefusal(item);
-    if (why === null) return { pill: nothing, buttons: nothing };
-    return { pill: nothing, buttons: actButton("drop", [item], { title: why || "send a stub instead of its reads from the next turn's start", disabled: !!why }) };
+    if (why !== null) buttons.push(actButton("drop", [item], { title: why || "send a stub instead of its reads from the next turn's start", disabled: !!why }));
+    if (item.pinned) buttons.push(actButton("unpin", [item], { title: "the model's forget_outputs may forget it again" }));
+    else if (forget && pinnable(item)) buttons.push(actButton("pin", [item], { title: "keep it from the model's forget_outputs (its later reads too)" }));
+    // A drop on some of its reads, others still sent: undrop takes it back.
+    if (undroppable(item)) buttons.push(undrop);
+    if (refreshable(item)) buttons.push(actButton("add", [item], { label: "refresh", title: "the next turn's note asks the model to read it again" }));
+    return { pill: nothing, buttons: buttons.length ? buttons : nothing };
   }
 
-  function rowTemplate(item, { session: inSession, group = null, now, pend = new Map() }) {
+  function rowTemplate(item, { session: inSession, group = null, now, pend = new Map(), forget = false }) {
     const fresh = isFresh(seenAt(item), now);
     const tag = stepTag(item, { session: inSession });
-    const words = `${opsText(item)}${fresh ? " · just now" : ""}`;
-    const glyph = item.muted ? GLYPHS.muted : fresh ? "●" : GLYPHS[item.kind] || "";
+    // An added row's words: what it is (a phone's tap on them opens its strip).
+    const words = item.added ? "added" : `${opsText(item)}${fresh ? " · just now" : ""}`;
+    const glyph = item.added ? "+" : item.muted ? GLYPHS.muted : fresh ? "●" : GLYPHS[item.kind] || "";
     const name = memberName(item, group);
     const full = item.kind === "file" ? item.path || item.key : item.kind === "url" ? item.url || item.key : item.key;
     let nameEl;
@@ -248,11 +289,12 @@ export function createWorkingSet({ historyEl, stageRoot = () => null, state, ses
     const state = item.state && item.state !== "live" ? ` ${item.state}` : "";
     const tokens = tokensText(item.tokens);
     const id = steerId(item);
-    const { pill, buttons } = rowActions(item, pend);
+    const { pill, buttons } = rowActions(item, pend, forget);
+    const pin = item.pinned ? html`<span class="ws-pin" title="pinned: the model's forget_outputs refuses it">📌</span>` : nothing;
     const isPending = pill !== nothing;
     const strip = stripOpen === id && buttons !== nothing;
     const open = item.kind === "file" ? html`<button type="button" class="ws-act-b open ref" data-ref-kind="file" data-ref-path=${item.ref?.path || full}>open</button>` : nothing;
-    const row = html`<div class=${`ws-row ${item.kind}${fresh ? " fresh" : ""}${item.muted ? " muted" : ""}${group ? " member" : ""}${state}${isPending ? " pending" : ""}${strip ? " strip-open" : ""}`} data-ws-id=${id}><span class="k">${glyph}</span>${nameEl}${edited ? html`<span class="e">✎</span>` : nothing}<span class="st">${words}</span>${pill}${tokens ? html`<span class="tk" title=${`about ${item.tokens} tokens of it are sent`}>${tokens}</span>` : nothing}${tagEl}${buttons !== nothing ? html`<span class="ws-act">${buttons}</span>` : nothing}</div>`;
+    const row = html`<div class=${`ws-row ${item.kind}${item.added ? " added" : ""}${fresh ? " fresh" : ""}${item.muted ? " muted" : ""}${group ? " member" : ""}${state}${isPending ? " pending" : ""}${strip ? " strip-open" : ""}`} data-ws-id=${id}><span class="k">${glyph}</span>${nameEl}${pin}${edited ? html`<span class="e">✎</span>` : nothing}<span class="st">${words}</span>${pill}${tokens ? html`<span class="tk" title=${`about ${item.tokens} tokens of it are sent`}>${tokens}</span>` : nothing}${tagEl}${buttons !== nothing ? html`<span class="ws-act">${buttons}</span>` : nothing}</div>`;
     // One template either way, so the tapped row stays the same node (a
     // click outside the popover closes it).
     return html`${row}${strip ? html`<div class="ws-strip">${buttons}${open}</div>` : nothing}`;
@@ -282,7 +324,8 @@ export function createWorkingSet({ historyEl, stageRoot = () => null, state, ses
     const memories = set.items.filter((i) => i.kind === "memory");
     const urls = set.items.filter((i) => i.kind === "url");
     const pend = pending();
-    const opts = { session: inSession, now, pend };
+    const forget = forgetOn(st.llmContext);
+    const opts = { session: inSession, now, pend, forget };
     const fileLabels = fold(files, POP_BUDGET).labels;
     // Memories are rows of their own; past the budget one group that opens.
     const memoryLabels = fold(memories, memories.length > POP_BUDGET ? 1 : Infinity).labels;
@@ -290,14 +333,17 @@ export function createWorkingSet({ historyEl, stageRoot = () => null, state, ses
     const memMeta = [`${memories.length - preloaded} used`, preloaded ? `${preloaded} preloaded` : "", set.muted.length ? `${set.muted.length} muted` : ""].filter(Boolean).join(" · ");
     const turnLabel = view.turn !== null && view.turn >= 0 ? `turn ${view.turn + 1}` : "this turn";
     const pct = Number.isFinite(st.ctxPct) ? ` · ctx ${Math.round(st.ctxPct)} %` : "";
-    const empty = !set.items.length && !set.muted.length;
+    const added = sendLine ? adding(pend) : [];
+    const empty = !set.items.length && !set.muted.length && !added.length;
     const tpl = html`<div class="ctx-pop-head"><strong>working set</strong><span class="ws-scope" role="group" aria-label="Scope"><button type="button" class=${!inSession ? "on" : ""} aria-pressed=${String(!inSession)} data-ws="scope" data-scope="turn" ?disabled=${view.turn === null || view.turn < 0}>${turnLabel}</button><button type="button" class=${inSession ? "on" : ""} aria-pressed=${String(inSession)} data-ws="scope" data-scope="session">session</button></span><span class="ctx-pop-kind">${set.items.length} item${set.items.length === 1 ? "" : "s"}${pct}</span>${ringTemplate(st.ctxPct)}<button type="button" class="ctx-pop-close" data-act="close" aria-label="Close">×</button></div>
       ${empty ? html`<div class="ctx-pop-meta">Nothing yet: the files, memories and URLs ${inSession ? "this session's turns read" : "this turn reads"} show here.</div>` : nothing}
       ${files.length ? html`<div class="ctx-pop-meta">files · ${files.length}</div>${labelsTemplate(fileLabels, opts)}` : nothing}
       ${memories.length || set.muted.length ? html`<div class="ctx-pop-meta">memories${memMeta ? ` · ${memMeta}` : ""}</div>${labelsTemplate(memoryLabels, opts)}${set.muted.map((m) => rowTemplate(m, opts))}` : nothing}
       ${urls.length ? html`<div class="ctx-pop-meta">urls · ${urls.length}</div>${labelsTemplate(fold(urls, POP_BUDGET).labels, opts)}` : nothing}
-      ${pend.size ? html`<div class="ws-pending" role="status">${pend.size} change${pend.size === 1 ? "" : "s"} pending · apply at the next turn's start · <button type="button" class="ws-act-b" data-ws="undo-all">undo all</button></div>` : nothing}
-      <div class="ctx-pop-meta ws-hint">A file opens its ref; a step tag goes to the call.${sendLine ? " Drop sends stubs instead of an item's reads from the next turn." : ""} Esc closes.</div>`;
+      ${added.length ? html`<div class="ctx-pop-meta">adding · ${added.length}</div>${added.map((it) => rowTemplate(it, opts))}` : nothing}
+      ${pend.size ? html`<div class="ws-pending" role="status"><span class="ws-pending-t">${pend.size} change${pend.size === 1 ? "" : "s"} pending<span class="ws-pending-when"> · apply at the next turn's start</span></span><button type="button" class="ws-act-b" data-ws="undo-all">undo all</button></div>` : nothing}
+      ${sendLine ? html`<form class="ws-add" data-ws="add-form"><input class="ws-add-in" type="text" name="key" placeholder="+ path, memory:NAME or URL" aria-label="Add to the working set: a path, memory:NAME or a URL" autocomplete="off" autocapitalize="off" spellcheck="false" enterkeyhint="go"><button type="submit" class="ws-act-b">add</button></form>` : nothing}
+      <div class="ctx-pop-meta ws-hint">A file opens its ref; a step tag goes to the call.${sendLine ? " Drop sends stubs instead of an item's reads from the next turn; add asks the model to read one first." : ""}${sendLine && forget ? " Pin keeps an item from the model's forget." : ""} Esc closes.</div>`;
     render(tpl, popover.pop);
   }
 
@@ -329,10 +375,10 @@ export function createWorkingSet({ historyEl, stageRoot = () => null, state, ses
   // Posts +op+ for the ids (the items' steer words, from the set).
   function steer(op, ids) {
     if (!sendLine || !ids.length) return;
-    const all = [...sessionSet().items, ...turnItems(view.turn)];
+    const all = [...sessionSet().items, ...turnItems(view.turn), ...adding()];
     const byId = new Map(all.map((it) => [steerId(it), it]));
     const items = ids.map((id) => byId.get(id)).filter(Boolean);
-    if (items.length) Promise.resolve(sendLine(steerLine(op, items))).catch(() => {});
+    if (items.length) Promise.resolve(sendLine(steerLine(op, items, state().dir))).catch(() => {});
   }
 
   popover.pop.addEventListener("click", (e) => {
@@ -349,10 +395,10 @@ export function createWorkingSet({ historyEl, stageRoot = () => null, state, ses
     }
     if (!act) return;
     if (act.dataset.ws === "steer") {
-      steer(act.dataset.op, act.dataset.ids.split(" ").filter(Boolean));
+      steer(act.dataset.op, JSON.parse(act.dataset.ids || "[]"));
     } else if (act.dataset.ws === "undo-all") {
       const pend = pending();
-      for (const op of ["drop", "undrop"]) {
+      for (const op of STEER_OPS) {
         const ids = [...pend].filter(([, o]) => o === op).map(([id]) => id);
         steer(INVERSE[op], ids);
       }
@@ -398,6 +444,12 @@ export function createWorkingSet({ historyEl, stageRoot = () => null, state, ses
     if (popover.isOpen()) popover.refresh();
   }
 
+  // The pending ops changed: the list and the rail's marks.
+  function pendingChanged() {
+    changed();
+    for (const fn of listeners) fn();
+  }
+
   // The footprints on the page (the history's, the hand-off's) drawn again
   // in place when their items' states changed: the same node (its focus,
   // the popover's opener), its children and label replaced.
@@ -466,12 +518,18 @@ export function createWorkingSet({ historyEl, stageRoot = () => null, state, ses
       refreshFootprints();
       fetchServer();
     },
+    // The session's strategy changed (/llm-context's command_ran): the open
+    // list redraws, its pin buttons shown only under forget (forgetOn).
+    strategyChanged() {
+      if (popover.isOpen()) popover.refresh();
+    },
     // A :working_set_updated event's set ({items, at}).
     update(snapshot) {
       events += 1;
       takeServer(snapshot, { event: true });
     },
-    // +fn()+ runs after each new server snapshot (the rail's redraw).
+    // +fn()+ runs after each new server snapshot and each change of the
+    // pending ops (the rail's redraw).
     onServer(fn) { listeners.add(fn); },
     // A command queued for after the running turn (its command_queued,
     // waits "turn_end"): a steer line is pending until its command_ran.
@@ -482,11 +540,11 @@ export function createWorkingSet({ historyEl, stageRoot = () => null, state, ses
       }
       if (event?.waits !== "turn_end" || !event.command_id || !parseSteerLine(event.line)) return;
       queued.set(event.command_id, event.line);
-      changed();
+      pendingChanged();
     },
     // A command ran (or was dropped): its line is no longer pending.
     commandRan(event) {
-      if (event?.command_id && queued.delete(event.command_id)) changed();
+      if (event?.command_id && queued.delete(event.command_id)) pendingChanged();
     },
     // The steer lines pending (for the specs and the rail).
     pending: () => pending(),

data/lib/samagotchi/web/session_access_routes.rb

@@ -0,0 +1,343 @@
+# frozen_string_literal: true
+
+require_relative "../session"
+require_relative "../session_access/local"
+require_relative "../session_inbox"
+require_relative "../reply_wait"
+require_relative "../pending_question"
+require_relative "../context_sources"
+require_relative "../context_command"
+require_relative "../send_command"
+require_relative "../launch_mode"
+require_relative "../model_profile"
+
+module Samagotchi
+  module Web
+    # The routes chi's session commands need from another machine's chi web
+    # (chi --remote NAME …, SessionAccess::Remote), one per
+    # SessionAccess::Local operation that the page's own routes don't cover:
+    # a prefix resolved, the CLI's list rows, a wait's pre-send state and
+    # the wait itself, a note, a push into a context source. Each calls
+    # SessionAccess::Local, so a Remote maps 1:1 onto them. Included in
+    # App: its ROUTES name the handlers, and its helpers (json_response,
+    # parse_json, …) answer. See docs/architecture.md (chi web's routes for
+    # the session commands).
+    module SessionAccessRoutes
+      # A wait route answers within this many seconds (status timeout); the
+      # client asks again until its own --timeout.
+      WAIT_MAX_SECONDS = 30.0
+      # GET /api/info's feature: this chi web has these routes (a remote
+      # client checks it before its first session command).
+      FEATURE = "session_commands"
+      # GET /api/info's feature: this chi web has the routes a remote
+      # attached TUI needs (wake, worker; chi --remote NAME --attach).
+      ATTACH_FEATURE = "remote_attach"
+      # The longest POST …/wake waits for a worker's Bridge
+      # (TerminalUI::AttachLauncher::BRIDGE_WAIT, an attach's here).
+      WAKE_MAX_WAIT = 10.0
+
+      private
+
+      # This server's sessions, as a session command reaches them here.
+      def session_access = @session_access ||= SessionAccess::Local.new(state_dir: @state_dir)
+
+      # A refusal an exception carries: its stable +code+, +detail+ (what
+      # the page shows; the message by default), and for a remote client
+      # the exception's own message and the fields its class is built from
+      # (session_id, reason, …), so it can raise the same class.
+      def refusal_response(status, code, error, detail: error.message, **fields)
+        json_response(status, { error: code, detail: detail, message: error.message, **fields }.compact)
+      end
+
+      # The body as a Hash ({} when there is none), or nil when it isn't one.
+      def body_hash(req)
+        raw = request_body(req)
+        return {} if raw.to_s.strip.empty?
+
+        parsed = parse_json(raw)
+        parsed.is_a?(Hash) ? parsed : nil
+      end
+
+      def truthy_param?(value) = %w[1 true yes].include?(value.to_s.strip.downcase)
+
+      # GET /api/sessions/resolve?id=PREFIX: the full id of the session an id
+      # or a unique prefix names (SessionAccess::Local#resolve). 200 {id};
+      # 404 not_found; 400 ambiguous_id with ids (the sessions it names).
+      def handle_resolve(req)
+        given = req.params["id"].to_s
+        return error_response(404, "not_found", "no session #{given[0, 80]}") unless Session.valid_id?(given)
+
+        json_response(200, { id: session_access.resolve(given) })
+      rescue Session::AmbiguousId => e
+        refusal_response(400, "ambiguous_id", e, ids: e.ids)
+      rescue ArgumentError
+        error_response(404, "not_found", "no session #{given[0, 80]}")
+      end
+
+      # GET /api/sessions/:id?brief=1: the session as a session command
+      # reads it (SessionAccess::Local#show): the file's status (not the
+      # displayed one), its names, folder, model and parent_answers, its
+      # owner's kind, and the file's pending question, never its messages.
+      # A chi web from before ?brief answers the whole read, which has the
+      # session part too.
+      def handle_brief_read(id)
+        session = @session_class.load(id, state_dir: default_state_dir)
+        owner = session_access.owner(id)
+        json_response(200, {
+          brief: true,
+          session: { id: session.id, status: session.status, title: session.title,
+                     display_title: session.display_title, project_root: session.project_root,
+                     working_directory: session.working_directory, model_name: session.model_name,
+                     model_typed: session.model_typed, parent_answers: session.parent_answers,
+                     owner: owner&.kind },
+          pending_question: session.pending_question&.to_file
+        })
+      end
+
+      # GET /api/sessions/summaries: the rows chi sessions list prints
+      # (SessionManager.session_summaries: status, live, busy, owner, recap,
+      # ctx_pct, waiting, …), filtered as its flags filter. Params: dir (a
+      # folder: its project's sessions; none: every project's), cwd (in that
+      # folder or below), live=1, archived=1, tests=0 (leave test runs out),
+      # sort, order, limit. An array, newest first by default.
+      def handle_summaries(req)
+        dir, error = scope_dir(req.params["dir"])
+        return error if error
+
+        cwd = req.params["cwd"].to_s
+        cwd = nil if cwd.strip.empty?
+        return error_response(400, "invalid_cwd", "cwd is an absolute path: #{cwd[0, 200]}") if cwd && !cwd.start_with?("/")
+
+        rows = session_access.summaries(
+          live: truthy_param?(req.params["live"]), cwd: cwd, limit: sanitize_limit(req.params["limit"]),
+          include_tests: !%w[0 false no].include?(req.params["tests"].to_s.strip.downcase),
+          project_root: dir && ProjectScope.root_for(dir), include_archived: truthy_param?(req.params["archived"]),
+          sort: sanitize_sort(req.params["sort"]), order: sanitize_order(req.params["order"])
+        )
+        json_response(200, rows)
+      end
+
+      # POST /api/sessions/:id/wait/prepare: what chi send --wait and chi
+      # answer read before anything is sent (SessionAccess::Local#
+      # prepare_wait). Body (all optional): question_id (the question the
+      # baseline counts as reported; absent: the one pending now, null:
+      # none), turn (--turn: known_turn says whether it can be waited for),
+      # created (a session just created: no reply, no question), busy (chi
+      # send --wait with a message: refuse a running turn, 409 busy or
+      # waiting in SendCommand::Busy's words, with its fields: question,
+      # parent_strategy; queue: true, --queue, refuses only a waiting
+      # question). 200 {session_id, cursor, baseline:
+      # {messages, question_id, last_turn}, own_turn, known_turn, running,
+      # live, settled, last_turn_id}.
+      def handle_wait_prepare(req, id)
+        body = body_hash(req) or return error_response(400, "invalid_json", "invalid JSON body")
+        turn = body["turn"]
+        return error_response(400, "invalid_turn", "turn is a turn id") unless turn.nil? || turn.is_a?(String)
+
+        session = session_access.show(id)
+        if body["busy"] == true
+          owner = session_access.owner(id) if session.status == Session::STATUS_RUNNING
+          busy = SendCommand::Busy.for(session, owner: owner, queue: body["queue"] == true)
+          return json_response(409, busy_json(busy)) if busy
+        end
+
+        question_id = body.key?("question_id") ? body["question_id"]&.to_s : :pending
+        start = session_access.prepare_wait(id, session: session, question_id: question_id, turn: turn,
+                                                created: body["created"] == true)
+        json_response(200, wait_start_json(id, start))
+      end
+
+      # A Busy refusal: its words here, and its fields, which a chi --remote
+      # client words with its own commands (SessionAccess::Remote#busy).
+      def busy_json(busy)
+        { error: busy.error, detail: busy.message, message: busy.message, session_id: busy.session_id,
+          question: busy.question&.to_file, parent_strategy: (strategy_json(busy.strategy) if busy.strategy) }.compact
+      end
+
+      def strategy_json(strategy) = { name: strategy.name, allowed: strategy.allowed, origin: strategy.origin.to_s }
+
+      def wait_start_json(id, start)
+        { session_id: id, cursor: start.cursor, baseline: start.baseline.to_h, own_turn: start.own_turn,
+          known_turn: start.known_turn, running: start.running, live: start.live, settled: start.settled,
+          last_turn_id: start.last_turn_id }
+      end
+
+      # POST /api/sessions/:id/wait: ReplyWait for at most WAIT_MAX_SECONDS
+      # (SessionAccess::Local#wait_reply). Body: cursor, baseline
+      # ({messages, question_id, last_turn}, as the prepare route gave it),
+      # turn, queued, ended_before, owner_grace (seconds, null: wait for
+      # whatever wakes a worker), timeout (seconds, capped). 200: the
+      # ReplyWait::Result's fields (status: done, waiting_for_answer,
+      # no_reply, error, stopped, timeout or worker_gone; text, file,
+      # question, outcome, …; never the Session) and parent_strategy, what
+      # a parent may pick on the session's questions here
+      # (ParentReport.strategy_for). A timeout status: ask again. 503
+      # server_stopping when chi web stops mid-wait.
+      def handle_wait(req, id)
+        body = body_hash(req) or return error_response(400, "invalid_json", "invalid JSON body")
+        options, error = wait_options(body)
+        return error if error
+
+        session_access.show(id)
+        result = session_access.wait_reply(id, **options, poll_interval: @wait_poll_interval,
+                                               cancelled: -> { !@server_running.call })
+        return error_response(503, "server_stopping", "chi web is stopping; wait again") if result.status == :canceled
+
+        json_response(200, wait_result_json(result, session_access.parent_strategy(id)))
+      end
+
+      # The wait's ReplyWait arguments from the body: [options, nil] or
+      # [nil, a 400 response].
+      def wait_options(body)
+        strings = %w[cursor turn].to_h { |key| [key, body[key]] }
+        if strings.any? { |_, value| !value.nil? && !value.is_a?(String) }
+          return [nil, error_response(400, "invalid_wait", "cursor and turn are strings")]
+        end
+
+        baseline, error = wait_baseline(body["baseline"])
+        return [nil, error] if error
+
+        numbers = %w[timeout owner_grace].to_h { |key| [key, body[key]] }
+        if numbers.any? { |_, value| !value.nil? && !(value.is_a?(Numeric) && value.positive?) }
+          return [nil, error_response(400, "invalid_wait", "timeout and owner_grace are positive seconds")]
+        end
+
+        timeout = [numbers["timeout"] || WAIT_MAX_SECONDS, WAIT_MAX_SECONDS].min
+        [{ cursor: strings["cursor"], turn: strings["turn"], baseline: baseline, timeout: timeout,
+           owner_grace: numbers["owner_grace"], queued: body["queued"] == true, ended_before: body["ended_before"] == true }, nil]
+      end
+
+      def wait_baseline(raw)
+        return [nil, nil] if raw.nil?
+
+        fields = { "messages" => Integer, "question_id" => String, "last_turn" => String }
+        unless raw.is_a?(Hash) && raw.all? { |key, value| fields.key?(key) && (value.nil? || value.is_a?(fields[key])) }
+          return [nil, error_response(400, "invalid_wait", "baseline is {messages, question_id, last_turn}")]
+        end
+
+        [ReplyWait::Baseline.new(**raw.transform_keys(&:to_sym)), nil]
+      end
+
+      RESULT_FIELDS = %i[text file outcome limit error_kind retryable cancel_reason stopped_by kept_steps turn_id origin].freeze
+
+      def wait_result_json(result, strategy)
+        json = { status: result.status.to_s }
+        RESULT_FIELDS.each { |key| json[key] = result[key] }
+        json[:text] = json[:text]&.dup&.force_encoding(Encoding::UTF_8)&.scrub
+        json[:question] = result.question&.to_file
+        json[:parent_strategy] = strategy_json(strategy)
+        json
+      end
+
+      # POST /api/sessions/:id/wake {wait}: the session's worker for a remote
+      # attach (SessionAccess::Local#wake): the live one, else resumed and
+      # waited for up to +wait+ seconds (WAKE_MAX_WAIT, also the most). 200
+      # {session_id, woke, worker: {epoch, started_at, version, features},
+      # model_name, default_model (this machine's config, for the TUI's
+      # status row), parent_strategy, installed (the newest chi here)}; 409
+      # owned_by_tui (a chi REPL has it), 409 scratch (a leftover scratch
+      # session, as chi --attach here says); 504 worker_timeout (its Bridge
+      # didn't come in time); 404 not_found.
+      def handle_wake(req, id)
+        body = body_hash(req) or return error_response(400, "invalid_json", "invalid JSON body")
+        wait = body.fetch("wait", WAKE_MAX_WAIT)
+        return error_response(400, "invalid_wait", "wait is positive seconds") unless wait.is_a?(Numeric) && wait.positive?
+
+        woken = session_access.wake(id, wait: [wait, WAKE_MAX_WAIT].min)
+        unless woken.sidecar
+          late = format(LaunchMode::BRIDGE_LATE, id)
+          return json_response(504, { error: "worker_timeout", detail: late, message: late, session_id: id })
+        end
+
+        json_response(200, { session_id: id, woke: woken.woke, worker: worker_json(woken.sidecar),
+                             model_name: session_access.show(id).model_name,
+                             default_model: ModelProfile.default_model_name,
+                             parent_strategy: strategy_json(session_access.parent_strategy(id)),
+                             installed: @hub&.installed })
+      rescue SessionManager::OwnedByTUI => e
+        owned_by_tui(e)
+      rescue SessionAccess::Refused => e
+        refusal_response(409, e.code, e, session_id: id)
+      end
+
+      # GET /api/sessions/:id/worker: the session's worker now, never
+      # started (SessionAccess::Local#worker): a remote attach's
+      # rediscovery and its features after a restart. 200 {session_id,
+      # live, stopped, owner: worker|tui|null, worker: {epoch, started_at,
+      # version, features}|null, parent_strategy}; 404 not_found.
+      def handle_worker(_req, id)
+        state = session_access.worker(id)
+        json_response(200, { session_id: id, live: state.live?, stopped: state.stopped, owner: state.owner&.kind,
+                             worker: state.sidecar && worker_json(state.sidecar),
+                             parent_strategy: strategy_json(session_access.parent_strategy(id)) })
+      end
+
+      # A live worker as a remote client knows it: its epoch is its
+      # identity (the one in its event ids).
+      def worker_json(sidecar)
+        { epoch: sidecar.epoch, started_at: sidecar.started_at, version: sidecar.version, features: sidecar.features }
+      end
+
+      # POST /api/sessions/:id/notes {text, source}: a context note for the
+      # session (NoteDelivery, as chi note; source: where it came from,
+      # "cli" by default, never "broadcast"). 200 {status: "queued" (a
+      # worker adds it) or "waits" (the next start does), session_id,
+      # queued}; 409 owned_by_tui (status refused: a chi REPL has it); 400
+      # note_rejected (empty, or over 16 KiB).
+      def handle_notes(req, id)
+        body = body_hash(req) or return error_response(400, "invalid_json", "invalid JSON body")
+        text = body["text"]
+        source = body.fetch("source", "cli")
+        return error_response(400, "missing_fields", "text is required") unless text.is_a?(String)
+        return error_response(400, "invalid_source", "source is a word") unless source.is_a?(String) && !source.strip.empty?
+        return error_response(400, "invalid_source", "source broadcast is chi broadcast's own") if source.strip == "broadcast"
+
+        session_access.show(id)
+        result = session_access.note(id, text: text, source: source.strip)
+        if result.status == :refused
+          error = SessionManager::OwnedByTUI.new(id)
+          return refusal_response(409, "owned_by_tui", error, session_id: id, status: "refused", queued: 0)
+        end
+
+        json_response(200, { status: result.status.to_s, session_id: id, queued: result.queued })
+      rescue SessionInbox::NoteRejected => e
+        error_response(400, "note_rejected", e.message)
+      end
+
+      # POST /api/sessions/:id/context/:name/push {text, summary, wake,
+      # hint}: new text for the session's --push source (chi context push;
+      # the fields as a source's JSON output gives them, checked the same
+      # way). 200 {status: "pushed", name, before, revision, changed}; 404
+      # not_found (no such source); 409 not_push (a command source); 400
+      # invalid_text.
+      def handle_context_push(req, id, name)
+        body = body_hash(req) or return error_response(400, "invalid_json", "invalid JSON body")
+        return error_response(400, "missing_fields", "text is required") unless body["text"].is_a?(String)
+
+        fetched = begin
+          ContextSources.parse_output(JSON.generate(body.slice("text", "summary", "wake", "hint")))
+        rescue ContextSources::Invalid => e
+          return error_response(400, "invalid_text", e.message)
+        end
+        pushed = session_access.context_push(context_target(id), name, fetched)
+        case pushed.status
+        when :missing then error_response(404, "not_found", "no source #{name[0, 40]}")
+        when :not_push then error_response(409, "not_push", SessionAccess::ContextPush.not_push_message(name))
+        else json_response(200, { status: "pushed", name: name, before: pushed.before, revision: pushed.revision,
+                                  changed: pushed.before != pushed.revision })
+        end
+      rescue ContextSources::Invalid
+        error_response(404, "not_found", "no source #{name[0, 40]}")
+      end
+
+      # The session as chi context's Target (SessionAccess::Local's context
+      # calls take one).
+      # @raise [ArgumentError] no such session
+      def context_target(id)
+        session = session_access.show(id)
+        ContextCommand::Target.new(session_id: id, project_root: session.project_root, cwd: session.working_directory,
+                                   label: id[0, 8])
+      end
+    end
+  end
+end

data/lib/samagotchi/worker_sidecar.rb

@@ -10,10 +10,14 @@ module Samagotchi
   # Bridge (port, bind), when it started (a new worker behind the same
   # "worker" owner), the chi it runs (chi update, the web's stale-worker
   # badge), the input-file format it reads (SessionInbox::INPUT_FORMAT) and
-  # what else it can do (Bridge::FEATURES). The Bridge writes it on start
+  # what else it can do (Bridge::FEATURES), and its Bridge's epoch (the
+  # one worker identity: the epoch in every event id, so a remote client
+  # tells a restarted worker apart; nil from a worker before it). The
+  # Bridge writes it on start
   # and removes it on stop; one a dead worker left stays until a client's
   # probe finds its port closed (.live with unlink: true).
-  class WorkerSidecar < Data.define(:port, :bind, :session_id, :started_at, :version, :input_format, :features)
+  class WorkerSidecar < Data.define(:port, :bind, :session_id, :started_at, :version, :input_format, :features,
+                                    :epoch)
     FILE = "bridge.json"
     # Seconds a liveness probe waits for the port to take a connect.
     PROBE_TIMEOUT = 0.2
@@ -29,7 +33,7 @@ module Samagotchi
       port = data["port"]
       new(port: port.respond_to?(:to_i) ? port.to_i : 0, bind: data["bind"], session_id: data["session_id"],
           started_at: data["started_at"], version: data["version"], input_format: data["input_format"],
-          features: Array(data["features"]).map(&:to_s))
+          features: Array(data["features"]).map(&:to_s), epoch: data["epoch"]&.to_s)
     rescue JSON::ParserError, SystemCallError
       nil
     end
@@ -63,13 +67,16 @@ module Samagotchi
     # @return [Integer, nil] .live's port
     def self.live_port(session_dir, unlink:, host: "127.0.0.1") = live(session_dir, unlink: unlink, host: host)&.port
 
-    def initialize(port:, bind: nil, session_id: nil, started_at: nil, version: nil, input_format: nil, features: []) = super
+    def initialize(port:, bind: nil, session_id: nil, started_at: nil, version: nil, input_format: nil, features: [],
+                   epoch: nil) = super
 
-    # Written whole or not at all; input_format only when it names one.
+    # Written whole or not at all; input_format and epoch only when they
+    # name one.
     def write(session_dir)
       FileUtils.mkdir_p(session_dir)
       record = to_h.transform_keys(&:to_s)
       record.delete("input_format") if input_format.nil?
+      record.delete("epoch") if epoch.nil?
       AtomicFile.write(self.class.path(session_dir), "#{JSON.pretty_generate(record)}\n")
     end
   end