samagotchi 0.152.0 → 0.154.0

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

@@ -0,0 +1,132 @@
+import { html } from "./vendor/lit-html.js";
+import { cantText } from "./format.js";
+import { workerBadgeFor } from "./info_bar_model.js";
+import { readStored, writeStored } from "./storage.js";
+import { createUpdateSheet } from "./update_sheet.js";
+import { mergeVersionState, restartConfirmText, updateFrameToast, versionNotice } from "./update_notice.js";
+
+// An available release's notice is once per version per browser, not per
+// tab: chi web says it in every snapshot until the owner updates.
+export const AVAILABLE_SHOWN_KEY = "chi_update_available_shown";
+
+// The owner page's chi versions (used by app.js): the versions carried by each
+// event snapshot and `chi` frame, the toasts they bring (chi web upgraded, a
+// newer one installed, an aged one available to update to), the update sheet
+// (update_sheet.js) and its `chi_update` frames, and the open session's
+// worker Restart.
+//
+// +store+: the page's session store (selected and current read; it writes no
+// field, only touch("infoBar"): the worker badge and the Restart button read
+// the versions and the restarting set). +toasts+: toasts.js's. +dialog+: the
+// update sheet's <dialog>. +loadedVersion+: the chi this page was loaded
+// from (body data-version). +api+: {updateChi, restartWorkers, restartWeb,
+// restartSession} (data.js). +confirm+, +reload+, +clipboard()+: the
+// browser's; +storage+: storage.js's guarded read and write.
+export function createVersionNotices({
+  store, toasts, dialog, loadedVersion, api,
+  confirm = (text) => globalThis.confirm(text),
+  reload = () => globalThis.location.reload(),
+  clipboard = () => globalThis.navigator?.clipboard,
+  storage = { read: readStored, write: writeStored },
+}) {
+  const toast = (text, action = null, options = {}) => { toasts.show(text, action, options); };
+  const sheet = createUpdateSheet({
+    dialog,
+    update: api.updateChi,
+    restartWorkers: api.restartWorkers,
+    restartWeb: api.restartWeb,
+  });
+  // Once per notice per tab: every reconnect's snapshot says it again.
+  const versions = { served: null, installed: null };
+  // The sessions whose Restart is under way (their button says so): one
+  // session's restart never blocks another's.
+  const restarting = new Set();
+  const shown = new Set();
+  const availableShown = storage.read(AVAILABLE_SHOWN_KEY);
+  if (availableShown) shown.add(`available:${availableShown}`);
+  let versionToast = null;
+
+  function notice(data) {
+    Object.assign(versions, mergeVersionState(versions, data));
+    const next = versionNotice({ loaded: loadedVersion, served: versions.served,
+                                 installed: versions.installed, available: versions.available,
+                                 updateBlocked: versions.updateBlocked, auto: versions.auto, restart: versions.restart,
+                                 autoOffers: versions.autoOffers, shown });
+    store.touch("infoBar"); // the worker badge compares with the newest installed
+    if (!next) return;
+    shown.add(next.key);
+    if (next.key.startsWith("available:")) storage.write(AVAILABLE_SHOWN_KEY, next.key.slice("available:".length));
+    const text = next.releaseUrl
+      ? html`${next.text} <a href=${next.releaseUrl} target="_blank" rel="noopener noreferrer">RubyGems</a>`
+      : next.text;
+    const action = next.reload
+      ? { label: "Reload", run: () => reload() }
+      : next.updateVersion
+        ? { label: "Update", run: () => sheet.install(next.updateVersion) }
+        : next.actions
+          ? next.actions.map((name) => ({
+            label: name === "restartWorkers" ? "Restart workers" : "Restart chi web",
+            run: () => (name === "restartWorkers" ? sheet.restartWorkers() : sheet.restartWeb()),
+          }))
+      : next.command
+        ? { label: "Copy", run: () => copyUpdateCommand(next.command) }
+        : null;
+    // One version toast at a time: a newer notice (Reload after a restart)
+    // supersedes the one before it.
+    toasts.dismiss(versionToast);
+    versionToast = toasts.show(text, action, { sticky: true });
+  }
+
+  // A `chi_update` frame (+snapshot+: the one an event snapshot carries).
+  function frame(data, { snapshot = false } = {}) {
+    const wasOpen = sheet.isOpen();
+    if (!sheet.receive(data)) return;
+    if (data.operation === "install" && data.state === "done" && data.version) notice({ installed: data.version });
+    const text = updateFrameToast(data, { wasOpen, snapshot });
+    if (text) toast(text, { label: "View", run: () => sheet.view() }, { sticky: true });
+  }
+
+  // An event snapshot's version after Restart chi web: the sheet says done.
+  function reconnected(version) {
+    if (sheet.reconnected(version)) toast(`chi web reconnected on chi ${version}`);
+  }
+
+  function copyUpdateCommand(command) {
+    const board = clipboard();
+    if (!board?.writeText) {
+      toast(`Clipboard unavailable; run ${command}`);
+      return;
+    }
+    board.writeText(command).then(
+      () => toast(`Copied ${command}`),
+      () => toast(`Couldn't copy ${command}`),
+    );
+  }
+
+  // The open session's worker badge (info_bar_model.js workerBadgeFor).
+  function badge() {
+    return workerBadgeFor(store.selected, store.current, versions);
+  }
+
+  // Restart: the session moves to a new worker on the newest chi; the page
+  // follows it (its bridge_up), the composer's draft stays as it is.
+  async function restart() {
+    const current = badge();
+    if (!current || !current.restart || restarting.has(store.selected)) return;
+    if (!confirm(restartConfirmText(store.current.workerVersion, current.newest))) return;
+    const id = store.selected;
+    restarting.add(id);
+    store.touch("infoBar");
+    try {
+      const result = await api.restartSession(id);
+      toast(result.version ? `Restarted on chi ${result.version}` : "Restarting: the new worker is starting");
+    } catch (e) {
+      toast(cantText("restart", e), null, { sticky: true });
+    } finally {
+      restarting.delete(id);
+      store.touch("infoBar");
+    }
+  }
+
+  return { notice, frame, reconnected, versions: () => versions, restarting, restart };
+}

data/lib/samagotchi/web/push/store.rb

@@ -7,7 +7,7 @@ require "openssl"
 require "time"
 require "uri"
 require_relative "crypto"
-require_relative "../private_files"
+require_relative "../../private_files"
 require_relative "../../log"
 require_relative "../../atomic_file"
 require_relative "../../session"

data/lib/samagotchi/web/session_access_routes.rb

@@ -256,7 +256,7 @@ module Samagotchi
       # status row), parent_strategy, installed (the newest chi here)}. A
       # worker still leaving is waited for first (Local#wake: its recap's
       # timeout and a margin, on top of +wait+); 409
-      # owned_by_tui (a chi REPL has it), 409 scratch (a leftover scratch
+      # owned_by_tui (a one-turn chi run has it), 409 scratch (a leftover scratch
       # session, as chi --attach here says); 504 worker_timeout (its Bridge
       # didn't come in time); 409 worker_newer (a worker whose protocol is newer
       # than this chi's, not resumed); 404 not_found.
@@ -425,7 +425,7 @@ module Samagotchi
       # 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
+      # queued}; 409 owned_by_tui (status refused: a one-turn chi run 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")
@@ -438,8 +438,9 @@ module Samagotchi
         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)
+          error = result.scratch ? SessionManager::ScratchSession.new(id) : SessionManager::OwnedByTUI.new(id)
+          return refusal_response(409, "owned_by_tui", error, session_id: id, status: "refused", queued: 0,
+                                                             scratch: result.scratch || nil)
         end
 
         json_response(200, { status: result.status.to_s, session_id: id, queued: result.queued })

data/lib/samagotchi/web/session_control.rb

@@ -16,7 +16,7 @@ module Samagotchi
     # a task, dequeue a queued turn, what it could stop and stop it
     # (handle_session_holds, handle_stop_holds — the page's Stop asks about
     # these first), stop, restart, archive, unarchive and delete
-    # (handle_question_answer … handle_delete), with the refusals they answer (owned_by_repl, owned_by_tui, archive_refused). Included in App:
+    # (handle_question_answer … handle_delete), with the refusals they answer (owned_by_one_shot, owned_by_tui, archive_refused). Included in App:
     # its ROUTES name the handlers, and its helpers (json_response,
     # error_response, parse_json, request_body, relay, not_live,
     # bridge_error, reply_detail, worker_timeout, bridge_client,
@@ -443,7 +443,7 @@ module Samagotchi
 
       # POST /api/sessions/:id/archive: hide it (and its delegates) from the
       # lists, keep it for good. A live idle worker is stopped first; a turn
-      # running in it or a delegate, a chi REPL's session and a scratch one
+      # running in it or a delegate, a one-turn chi run's session and a scratch one
       # are refused (409).
       def handle_archive(_req, id)
         result = @manager.archive_session(id, state_dir: @state_dir, wait: STOP_WAIT_SECONDS)
@@ -451,7 +451,7 @@ module Samagotchi
         json_response(200, { status: "archived", session_id: result.id, archived: result.archived,
                              stopped: result.stopped, discarded: result.discarded })
       rescue SessionManager::OwnedByTUI => e
-        owned_by_repl(id, e)
+        owned_by_one_shot(id, e)
       rescue SessionManager::ArchiveRefused => e
         archive_refused(e)
       end
@@ -466,7 +466,7 @@ module Samagotchi
       # DELETE /api/sessions/:id?force=true: the session for good. With
       # force a live worker is stopped first (the page sends it: its confirm
       # says so); without it a live worker's session is refused, 409
-      # worker_running, as chi sessions delete without --force. A chi REPL's
+      # worker_running, as chi sessions delete without --force. A one-turn chi run's
       # session is always refused.
       def handle_delete(req, id)
         result = @manager.delete_session(id, state_dir: @state_dir, stop: truthy_param?(req.params["force"]),
@@ -474,7 +474,7 @@ module Samagotchi
         @hub&.touch(result[:id])
         json_response(200, { status: "deleted", session_id: result[:id], stopped: result[:stopped] })
       rescue SessionManager::OwnedByTUI => e
-        owned_by_repl(id, e)
+        owned_by_one_shot(id, e)
       rescue SessionManager::DeleteRefused => e
         detail = e.reason == :still_stopping ? "#{e.message}; try again in a moment" : e.message
         refusal_response(409, e.reason.to_s, e, detail: detail, session_id: e.session_id, reason: e.reason.to_s)
@@ -482,15 +482,19 @@ module Samagotchi
 
       # 409 owned_by_tui in the words a refused archive, delete or continue
       # shows (stop, restart, a turn and a command show OwnedByTUI's own).
-      def owned_by_repl(id, error = nil)
+      def owned_by_one_shot(id, error = nil)
         named = SessionManager::OwnedByTUI.new(id)
         error ||= named
         refusal_response(409, "owned_by_tui", error, detail: named.message, session_id: error.session_id)
       end
 
       # 409 owned_by_tui in OwnedByTUI's own words (stop, restart, a turn, a
-      # command).
-      def owned_by_tui(error) = refusal_response(409, "owned_by_tui", error, session_id: error.session_id)
+      # command); scratch: true for a chi scratch session
+      # (SessionManager::ScratchSession), which a remote client raises again.
+      def owned_by_tui(error)
+        scratch = error.is_a?(SessionManager::ScratchSession) || nil
+        refusal_response(409, "owned_by_tui", error, session_id: error.session_id, scratch: scratch)
+      end
 
       # 409 scratch or busy (every other reason: a turn, a queued prompt, an
       # open step-limit question, in it or a delegate, +busy_id+), with the

data/lib/samagotchi/web/session_create.rb

@@ -339,7 +339,7 @@ module Samagotchi
       rescue SessionManager::ArchiveRefused => e
         [nil, archive_refused(e)]
       rescue SessionManager::OwnedByTUI => e
-        [nil, owned_by_repl(given, e)]
+        [nil, owned_by_one_shot(given, e)]
       rescue ModelProfile::MissingModel => e
         [nil, error_response(400, "invalid_model", e.message)]
       rescue Session::AmbiguousId => e

data/lib/samagotchi/web/session_hub.rb

@@ -41,8 +41,8 @@ module Samagotchi
       # The flock leaves no file trace when its holder dies, so owners are
       # probed: every tick for the sessions the projection believes owned
       # (a handful; OwnerLock.owner is open + LOCK_SH|LOCK_NB + close), and
-      # all sessions this often (a plain REPL that opened an old session
-      # without saving it has no file signal until its first save).
+      # all sessions this often (a one-shot or an older chi's REPL that
+      # opened an old session without saving it has no file signal until its first save).
       FULL_PROBE_INTERVAL = 10.0
 
       # What a subscriber gets: `session` with {session: summary} for an

data/lib/samagotchi/web/session_show.rb

@@ -120,8 +120,8 @@ module Samagotchi
       end
 
       # The file's question only while a worker owns the session: one a
-      # dead worker saved can't be answered (its turn is gone), nor a chi
-      # REPL's (it shares nothing with the web).
+      # dead worker saved can't be answered (its turn is gone), nor a
+      # one-shot's or an older chi's REPL's (they share nothing with the web).
       # A question between turns (the step-limit one) is the snapshot's own.
       # Its refs (the asking reply's, QuestionAsked) are checked again.
       def shown_pending_question(session, turn_snapshot, owner)

data/lib/samagotchi/web/session_summary.rb

@@ -108,7 +108,7 @@ module Samagotchi
           # For the tab's notifications (notify.js): an open question, the
           # running turn's open card with actions, and how the last turn
           # ended. A question saved by a worker that died is not open, nor a
-          # chi REPL's (only a worker shares it).
+          # one-turn chi run's (only a worker shares it).
           pending_question: session.waiting_question(live: !!owner&.worker?),
           pending_card: up ? Bridge::PendingCard.read(session_dir) : nil,
           last_turn: session.last_turn&.to_file,

data/lib/samagotchi/worker.rb

@@ -14,6 +14,7 @@ require_relative "turn_note"
 require_relative "steer"
 require_relative "turn_origin"
 require_relative "worker_idle_exit"
+require_relative "degrade"
 require_relative "hold_stop"
 require_relative "children_status"
 require_relative "worker_wakes"
@@ -51,7 +52,7 @@ module Samagotchi
   # It runs the session's Engine and Bridge, takes queued prompts from the
   # input dir one turn at a time, and returns when nobody has used it for the
   # idle-exit timeout. A failed turn is rolled back and its prompt handed back
-  # (:prompt_restored), as in the REPL, and the loop goes on. A stop marked on
+  # (:prompt_restored), and the loop goes on. A stop marked on
   # disk exits the process; an error outside a turn marks the session and
   # exits with 1.
   #
@@ -188,6 +189,10 @@ module Samagotchi
     # checks again then).
     def discard? = @discard
 
+    # Whether this worker runs a `chi scratch` session: deleted as it leaves
+    # (SessionManager.run_session_loop).
+    def scratch? = !!@session&.scratch
+
     # Whether delegate reports wait that an idle parent runs a turn for
     # (#wake_state): SessionManager.run_session_loop starts a new worker
     # for them after this one leaves. Reports the budget or a failure held
@@ -201,8 +206,9 @@ module Samagotchi
     #   to exit (Bridge POST /exit), :restart when it asked for a restart
     #   (the caller starts a new worker), :stopped when the session was stopped
     #   (chi stop), :signal when a signal stopped it (WorkerSignals),
-    #   :crashed when the loop raised (the session is marked errored);
-    #   SessionManager.run_session_loop turns it into the exit
+    #   :crashed when the loop raised (the session is marked errored),
+    #   :scratch_left when a scratch session's terminal is gone (the caller
+    #   deletes it); SessionManager.run_session_loop turns it into the exit
     def run
       # The thread a signal's expired grace raises in (the main thread in a
       # worker process).
@@ -248,6 +254,8 @@ module Samagotchi
     # The session, its Engine and what runs its turns, before anyone can
     # reach it.
     def start
+      # A scratch worker's grace for its terminal's first stream counts from here.
+      @started_at = monotonic_now
       # The wake turns' budget (delegate reports, attached context, peers), from now.
       @wakes = WorkerWakes.new(grace: WAKE_START_GRACE)
       # This worker holds the session now (a continue's starting marker held
@@ -340,7 +348,7 @@ module Samagotchi
                                      @bridge.queue_command(line, client_id: client_id, after_file: after_file,
                                                                  enqueued_id: enqueued_id, author: author)
                                    })
-      # /model's default is the config's, as in the REPL; the Engine started
+      # /model's default is the config's; the Engine started
       # on the session's model.  nil when there is no default.model.
       @default_model = ModelProfile.default_model_name
       @commands = SessionCommands.new(engine: @engine, turn_flow: @turn_flow,
@@ -416,6 +424,31 @@ module Samagotchi
       @context_poller = ContextPoller.new(session_id: @session_id, state_dir: @state_dir,
                                           project_root: @session.project_root, cwd: @session.working_directory,
                                           on_change: -> { @waker.wake }).start
+      @scratch_watch = start_scratch_watch if @session.scratch
+    end
+
+    # A scratch session's turn never runs on with no terminal: a turn
+    # waiting on a question or an approval would keep the worker up for
+    # nobody. Each tick while a turn runs and its terminal is gone
+    # (#scratch_unattended?), the question is dropped and the turn
+    # cancelled as a stop cancels it; the idle pass then leaves
+    # (:scratch_left) and the session is deleted.
+    def start_scratch_watch
+      Thread.new do
+        loop do
+          sleep(@poll_interval)
+          Degrade.call(:worker, "scratch_watch_failed") { cancel_unattended_turn }
+        end
+      end.tap { |thread| thread.report_on_exception = false }
+    end
+
+    def cancel_unattended_turn
+      return unless @engine.turn_running? && scratch_unattended?
+
+      Log.info(:worker, "scratch_turn_cancelled", sid: @session_id)
+      @engine.cancel_question(SessionManager::STOP_CANCEL_REASON) if @engine.pending_question
+      @engine.cancel_current_turn!(SessionManager::STOP_CANCEL_REASON.to_sym)
+      @waker.wake
     end
 
     # One pass of the loop: the first work found runs (queued commands, a
@@ -468,6 +501,7 @@ module Samagotchi
       return if run_wake_turn
       return if run_task_wake
       return if run_due_reminders
+      return left(:scratch_left) if scratch_unattended? && !@engine.turn_running? && leave_scratch
       return left(:idle_exit) if @idle_exit.due? && leave_idle
 
       leaving = @exit_requested && leave_on_request
@@ -553,6 +587,7 @@ module Samagotchi
     TEARDOWN_LEAVE_WAIT = 10
 
     def teardown
+      @scratch_watch&.kill
       @config_restart_unsubscribe&.call
       @context_poller&.stop
       drop_queued_commands
@@ -571,6 +606,8 @@ module Samagotchi
       engine = nil
       engine = Samagotchi::Engine.new(
         model_name: @session.model_name,
+        # `chi scratch`: no memory_write, no delegates, approvals in memory.
+        scratch: @session.scratch,
         model_typed: @session.model_typed,
         # The session's --memory and --mute lists: the same prompt on every
         # (re)spawn.
@@ -783,7 +820,7 @@ module Samagotchi
     end
 
     # A participant's cap in dollars: their own, else the config's.
-    def participant_cap(entry) = entry&.cap.is_a?(Numeric) ? entry.cap.to_f : Web::Grants.default_cap
+    def participant_cap(entry) = entry&.cap.is_a?(Numeric) ? entry.cap.to_f : Grants.default_cap
 
     # A participant's cleaned name, else their id.
     def participant_label(author, name)
@@ -830,7 +867,7 @@ module Samagotchi
       nil
     end
 
-    # A due reminder runs as a continue turn, as in the REPL: Engine#run_turn
+    # A due reminder runs as a continue turn: Engine#run_turn
     # injects the reminders as a tail system message, and no user message is
     # added. A prompt's turn may have injected them already (a stale latch):
     # then there is nothing to run.
@@ -1414,7 +1451,7 @@ module Samagotchi
     # WorkerInbound.save_or_log: a failed save between turns is logged.
     def save_or_log(at, &) = WorkerInbound.save_or_log(at, &)
 
-    # Back to the conversation before the failed turn, as the REPL does (so
+    # Back to the conversation before the failed turn (so
     # failed prompts don't pile up as consecutive user messages), and each
     # prompt it took (its own and any merged into it) goes back to its
     # sender, who can send it again. The rollback and the announcements are
@@ -1559,6 +1596,57 @@ module Samagotchi
       end
     end
 
+    # How long a scratch worker waits for its terminal's first stream
+    # (AttachLauncher attaches within BRIDGE_WAIT of the spawn).
+    SCRATCH_JOIN_GRACE = 30
+
+    # How long a scratch worker's terminal may have no stream open, after
+    # it had one, before it counts as gone: twice the attached terminal's
+    # whole reconnect ladder (TerminalUI::LocalLink#reconnect_delays), so
+    # a reconnect gap (a dropped stream, a slow worker) never reads as a
+    # terminal that left.
+    SCRATCH_GONE_AFTER = 2 * BridgeClient::EventStream::REDISCOVER_DELAYS.sum
+
+    # Whether this is a `chi scratch` session's worker whose terminal is
+    # gone: no stream open for SCRATCH_GONE_AFTER, after one was (a killed
+    # TUI's closes as its writer reads the hang-up), or none came within
+    # SCRATCH_JOIN_GRACE. Its terminal deletes it on every way out it sees;
+    # this is for the ones it doesn't (kill -9, a closed terminal window).
+    def scratch_unattended?
+      return false unless @session&.scratch && @bridge
+
+      if @bridge.open_streams.positive?
+        @unattended_since = nil
+        return false
+      end
+      return monotonic_now - @started_at >= SCRATCH_JOIN_GRACE unless @bridge.streams_served.positive?
+
+      # Set by the first look (the scratch watch or the idle pass) that
+      # finds no stream; a stream back resets it above.
+      @unattended_since ||= monotonic_now
+      monotonic_now - @unattended_since >= SCRATCH_GONE_AFTER
+    end
+
+    def monotonic_now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+    # #leave_idle for a scratch worker its terminal left: checked again with
+    # the event log held, then the intake closes. The session is deleted
+    # once the lock is free (SessionManager.run_session_loop: :scratch_left).
+    # @return [Boolean] false when a client came back since
+    def leave_scratch
+      stop_bridge_after do
+        @engine.synchronize_events do
+          # A turn still running is the scratch watch's to cancel first.
+          next false unless scratch_unattended? && !@engine.turn_running?
+
+          @bridge&.close_intake
+          @engine.stop_idle(join: false)
+          Log.info(:worker, "scratch_left", served: @bridge.streams_served)
+          true
+        end
+      end
+    end
+
     # Check again with the event log held, which the Bridge holds while it
     # queues a POST /turn, then close the Bridge's intake so no client can
     # queue one after the check, and stop the idle jobs (reminder callback,
@@ -1694,6 +1782,9 @@ module Samagotchi
     # @return [WorkerIdleExit::Hold, nil]
     def exit_hold(client_id, kind:, stop:, ask:)
       if kind == :restart
+        # A scratch session's worker ends with its terminal: never restarted.
+        return WorkerIdleExit::Hold.new(reason: :scratch) if @session.scratch
+
         hold = @idle_exit.hold_for_restart
         return hold && WorkerIdleExit::Hold.new(reason: hold)
       end
@@ -1792,14 +1883,20 @@ module Samagotchi
     # A restart keeps even an empty session (a new worker takes it over at
     # once) and leaves the recap to the conversation's next real pause.
     def left(result)
-      deleting = result == :exit_requested && @exit_deletes
+      deleting = (result == :exit_requested && @exit_deletes) || result == :scratch_left
+      # The attached context goes with this process: a change that landed after
+      # the leaving pass looked at it has no later pass to note it, so note it
+      # here (no wake turn: the worker is on its way out). Not into a session
+      # /exit --delete deletes next: its save could land after the delete and
+      # write the session back.
+      absorb_context unless deleting
       # The watch goes with this process: a task that finished since the
       # last look (nothing held the exit for it: queue, a note-only task,
       # /exit) is a plain note for the next turn, not lost. Not into a
       # session /exit --delete deletes next: its save could land after the
       # delete and write the session back.
       @task_wakes.absorb unless deleting
-      return result if result == :restart
+      return result if %i[restart scratch_left].include?(result)
 
       @discard = empty_session?
       write_recap_on_leave unless @discard || deleting

data/lib/samagotchi/worker_link.rb

@@ -23,9 +23,9 @@ module Samagotchi
   #   past START_LIMIT without one;
   # - Leaving: the worker closed its Bridge and holds the lock for its last work;
   # - Skew: a worker whose sidecar speaks a newer PROTOCOL than this chi;
-  # - Stale: a sidecar, but the lock is free (or a chi REPL holds it, which
+  # - Stale: a sidecar, but the lock is free (or a one-turn chi run holds it, which
   #   writes none): its worker died;
-  # - None: no worker and no sidecar, or a chi REPL.
+  # - None: no worker and no sidecar, or a one-turn chi run.
   # A kernel releases a dead worker's lock, so a free lock is the proof of
   # death a TCP probe never gave (a port can be reused by another session's
   # Bridge).
@@ -80,7 +80,7 @@ module Samagotchi
     end
 
     # No worker: no sidecar in the session folder, and no worker's lock (a
-    # chi REPL's, +owner+, is no worker's).
+    # one-turn chi run's, +owner+, is no worker's).
     None = Data.define(:owner) do
       def initialize(owner: nil) = super
 

data/lib/samagotchi/working_set_command.rb

@@ -3,6 +3,7 @@
 require_relative "working_set"
 require_relative "working_set_steer"
 require_relative "tools/memory"
+require_relative "session"
 
 module Samagotchi
   # /working-set: with no arguments the session's working set (WorkingSet,
@@ -50,7 +51,7 @@ module Samagotchi
       return [listing, [], :ok] if verb.nil?
       raise ArgumentError, USAGE unless VERBS.include?(verb) && !words.empty?
 
-      session = @engine.session or raise ArgumentError, "no session yet"
+      session = @engine.session or raise ArgumentError, Session::NONE_YET
       cwd = session.working_directory
       strategy = @engine.working_set_strategy
       messages = @engine.clone_messages(session.messages)
@@ -79,7 +80,7 @@ module Samagotchi
     # The set under the strategy the next turn runs, and the pending ops.
     def listing
       session = @engine.session
-      return "no session yet" unless session
+      return Session::NONE_YET unless session
 
       messages = Array(session.messages)
       items = WorkingSet.build(messages, cwd: session.working_directory, strategy: @engine.working_set_strategy,