Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

47.9 KB
Raw Blame
/// The paired daemon's face in the status line: its mood, its blinks, the
/// frames it steps through while agents work and the one line it says.
///
/// The rules are the README's (`daemons/README.md`, Moods, Motion and blinks,
/// Voice). Moods come from work. Illustrated idle motion has a separate visual clock.
///
/// - **Motion** is driven by work, not by time: while agents work, the work
///   frame steps once per real agent event ([pulse]), at most twice a second,
///   so a baton that stops means an agent that stopped. The only timers end a
///   held reaction, run decorative motion, end a nap and clear a line.
///   Reduce Motion, a background window and the Motion setting stop them all;
///   the face still changes.
/// - **Interruptions**: only a harness waiting on you and a failure take over
///   the status line, in the message yellow, at most one line nobody asked for
///   every two minutes, never about the pane in front of you, and only after
///   Enter, a pane switch or 8 s without a key. Finished turns become `3 done`
///   beside the daemon, cleared when you look. Replies (a boop, its first
///   words, why an answer failed, the pair answering you) are dim. Quiet
///   silences everything.
/// - **The pair brain's lines** (`daemon_say`) are shown exactly as sent,
///   keys first (`[y/n/g] api@office Bash: npm test`), for their `ttlMs`:
///   their keys work only while the line shows, and only once the window has
///   drawn it and its `detail` (the daemon's `daemon_shown` rule). A line the
///   pair harness wrote (`from: 'pair'`) is drawn as it speaking.
library;

import 'dart:async';

import 'package:flutter/foundation.dart';

import 'daemon_brain.dart';
import 'illustrated_styles.g.dart';
import 'daemon_lines.dart';
import 'daemon_plate_client.dart';
import 'daemon_settings.dart';
import 'individuals.dart';
import 'render.dart';
import 'roster.dart';
import 'zoo.dart';
import 'zoo_controller.dart';

/// A harness a line may be about: `machineId/agentId`, with what the window
/// knows of it to fill a line's slots.
@immutable
class DaemonSubject {
  const DaemonSubject(this.key, {this.who, this.q, this.recap, this.since});

  /// `machineId/agentId`.
  final String key;

  /// `engine@machine`.
  final String? who;

  /// Its question, its turn's recap, and since when it has waited.
  final String? q, recap;
  final DateTime? since;
}

/// A turn that ended in a harness this window can see, newest last.
@immutable
class DaemonTurnEnd {
  const DaemonTurnEnd(this.subject, {this.failed = false});
  final DaemonSubject subject;
  final bool failed;
}

/// What the workspace is doing, as the daemon watches it.
@immutable
class DaemonWatch {
  const DaemonWatch({
    this.working = false,
    this.workingCount = 0,
    this.needIds = const {},
    this.needs = const {},
    this.failing = false,
    this.failed = const [],
    this.turns = const {},
    this.fails = const {},
    this.ended = const {},
    this.idleCount = 0,
    this.focus,
    this.away = const [],
    this.asks = 0,
    this.doneCount,
    this.doneLast = const [],
    this.autonomy,
    this.autonomyRequested,
  });

  /// Any agent is working, and how many.
  final bool working;
  final int workingCount;

  /// Harnesses waiting on you, by a stable id per question
  /// (`machineId/agentId#requestId`), and what is known of each.
  final Set<String> needIds;
  final Map<String, DaemonSubject> needs;

  /// A harness you have open failed to start or its last turn failed. A
  /// machine that is asleep or unreachable is not a failure ([away]).
  final bool failing;
  final List<DaemonSubject> failed;

  /// Finished and failed turns you started, counted per machine, and the
  /// last few that ended per machine (who they were).
  final Map<String, int> turns, fails;
  final Map<String, List<DaemonTurnEnd>> ended;

  /// Open harnesses with nothing to do.
  final int idleCount;

  /// The pane in front of you, `machineId/agentId`: never spoken about.
  final String? focus;

  /// Machines that are asleep, out of reach or otherwise not there: shown
  /// calmly, never as a failure (`offline` when only the window can tell).
  final List<DaemonMachine> away;

  /// Proposals from the pair waiting for your key (`daemon_state.asks`): it
  /// asks you something, so the face is `need`.
  final int asks;

  /// The brain's count of turns finished since you looked
  /// (`daemon_state.done.count`, every machine), when there is a brain; the
  /// window counts its own otherwise. And the last few, as lines.
  final int? doneCount;
  final List<String> doneLast;

  /// The level the daemon acts at (`daemon_state.autonomy`), and a higher one
  /// waiting for the person's yes. Null without a brain that says.
  final String? autonomy, autonomyRequested;
}

enum _LineKind {
  /// Something needs you or failed: the message line, in yellow. Nobody
  /// asked for it: at most one every two minutes, never mid-thought.
  alert,

  /// The pair asks for your key on something you asked it to do: yellow,
  /// and at once (its keys work only while it shows).
  ask,

  /// Something a rule or the pair did on its own (`auto`): dim, and like an
  /// alert nobody asked for it.
  report,

  /// You asked (a boop, a hatch, an answer, a talk): dim, in the status
  /// line's ink, at once.
  reply;

  bool get yellow => this == alert || this == ask;
  bool get unsolicited => this == alert || this == report;
}

class DaemonFace extends ChangeNotifier {
  DaemonFace(
    this.zoo, {
    DaemonRoster? roster,
    DateTime Function()? now,
    DaemonSettings? settings,
    this.animateIllustrations = false,
  }) : roster = roster ?? zoo.roster,
       settings = settings ?? DaemonSettings(),
       _ownsSettings = settings == null,
       _now = now ?? DateTime.now {
    zoo.addListener(_zooChanged);
    this.settings.addListener(_settingsChanged);
    _events = zoo.events.listen(_zooEvent);
  }

  final ZooController zoo;

  /// Enabled by a mounted illustration surface; headless state observers stay idle.
  final bool animateIllustrations;
  final DaemonSettings settings;

  /// Individuals' own plates from this computer's harness process, when the
  /// window has a way to ask (the panel's portraits and cards).
  DaemonPlateClient? plates;
  final bool _ownsSettings;
  late final StreamSubscription<ZooEvent> _events;

  /// How long a new egg shows in the slot before the daemon comes back.
  static const eggShowFor = Duration(seconds: 3);
  final DaemonRoster roster;
  final DateTime Function() _now;

  static const doneCooldown = Duration(seconds: 20);
  static const backAfter = Duration(minutes: 15);
  static const napLength = Duration(minutes: 15);
  static const lookEvery = Duration(milliseconds: 2500);
  static const voiceFor = Duration(milliseconds: 5200);

  /// A line nobody asked for waits until 8 s after the last key (or Enter,
  /// or a pane switch), and is dropped if it still waits after 20 s.
  static const typingQuiet = Duration(seconds: 8);
  static const voiceExpires = Duration(seconds: 20);

  /// At most one line nobody asked for this often.
  static const unsolicitedEvery = Duration(minutes: 2);

  /// Work frames step at most this often.
  static const stepEvery = Duration(milliseconds: 500);

  /// How long a roster line waits for the brain's own line about the same
  /// moment (`daemons/BRAIN.md`: prefer a `daemon_say` within 2.5 s).
  static const brainWait = Duration(milliseconds: 2500);

  /// A line with answers stays up this long unless its `ttlMs` says otherwise
  /// or it is answered, withdrawn or dismissed.
  static const askFor = Duration(seconds: 30);

  bool _disposed = false;
  bool _foreground = true, _reduceMotion = false;
  bool _revealing = false;

  // What it watches.
  bool _working = false, _failing = false;
  int _workingCount = 0, _idleCount = 0;
  Set<String> _needIds = const {};
  Map<String, DaemonSubject> _needs = const {};
  List<DaemonSubject> _failed = const [];
  List<DaemonMachine> _away = const [];
  int _asks = 0;
  String? _autonomy, _autonomyRequested;
  int? _brainDone;
  List<String> _doneLast = const [];
  String? _focus;
  final _heardNeeds = <String>{};
  final _turns = <String, int>{}, _fails = <String, int>{};
  bool _baselined = false;

  // Activity details: finished turns since you looked, and while you were away.
  int _doneCount = 0, _doneWhileAway = 0;
  Timer? _seenTimer;

  /// You looked at the finished-turn count: the brain hears `doneSeen`.
  VoidCallback? onSeen;

  /// Coming back to the window is a look at the finished-turn count, once it
  /// has been in front this long.
  static const seenAfterFocus = Duration(seconds: 4);

  // Held faces.
  DaemonMood? _held;
  Timer? _holdTimer;
  bool _booped = false;
  Timer? _boopTimer;
  DateTime? _napUntil;
  Timer? _napTimer;
  DateTime? _awayAt, _lastDone, _lastLook;

  // Blinks, work steps and the wave.
  String? _lid;
  Timer? _blinkTimer;
  int _step = 0;
  DateTime? _lastStep;
  Timer? _stepTimer;
  Timer? _artTimer;
  int _artFrame = 0;
  String? _artKey;

  /// Decorative motion has its own clock; work still advances only on real events.
  int get artFrame => !motionEnabled || quiet
      ? 0
      : mood == DaemonMood.work
      ? steps
      : _artFrame;
  int _backT = 0;
  Timer? _backTimer;

  // Voice.
  final _voice = ValueNotifier<String?>(null);
  Timer? _voiceTimer;
  _Line? _pendingVoice;
  _Line? _spoken;
  DateTime? _lastUnsolicited;

  /// Whether this harnessd's pair brain is talking (it sent `daemon_state`).
  bool brainActive = false;
  Timer? _pendingTimer;
  DateTime? _lastKey;

  /// A dialog, picker or the reveal is open: lines wait.
  bool Function() dialogOpen = _never;
  static bool _never() => false;

  String? _pairKey;
  ZooEgg? _arriving;
  Timer? _arrivingTimer;

  // ── what it shows ──────────────────────────────────────────────────────────

  bool get visible => zoo.loaded;
  bool get motionEnabled => _foreground && !_reduceMotion && settings.motion;
  bool get revealing => _revealing;
  bool get napping => _napUntil != null;
  bool get quiet => settings.quiet;

  /// The paired individual, withheld while its hatch reveal is still
  /// running.
  ZooDaemon? get daemon => _revealing ? null : zoo.paired;

  /// Its species: its lines, its first words, its colour.
  DaemonDef? get def => roster.byId(daemon?.id);

  /// Its traits (README, "Individuals"), from its seed.
  DaemonTraits? get traits => zoo.traitsOf(daemon);

  /// The species as this individual shows it in the status line: a rare
  /// extra's sprites, a fidgety one's pace (render.mjs `individualDaemon`).
  DaemonDef? get spriteDef {
    final d = daemon;
    return d == null ? null : individualDaemon(roster, d.id, traits);
  }

  /// `pip`, the name it was given at the hatch, else its species.
  String get name => daemon?.name ?? def?.id ?? '';
  int get versionIndex => roster.versionIndex(daemon?.version);
  bool get shiny => daemon?.shiny == true;

  bool get eggReady => daemon == null && zoo.readyEgg != null;

  /// Work frames step at most this often: half as long for a fidgety
  /// individual, whose work frames turn at half `workMs`.
  Duration get stepInterval {
    final d = def, s = spriteDef;
    if (d == null || s == null || s.workMs >= d.workMs || d.workMs <= 0) {
      return stepEvery;
    }
    return stepEvery * (s.workMs / d.workMs);
  }

  DaemonMood get mood {
    if (_booped) return DaemonMood.boop;
    // A harness waiting on you, or the pair asking for your key.
    if (_needIds.isNotEmpty || _asks > 0) return DaemonMood.need;
    if (napping) return DaemonMood.nap;
    if (_held case final held?) return held;
    if (_working) return DaemonMood.work;
    if (_failing) return DaemonMood.fail;
    return DaemonMood.idle;
  }

  /// The blink lid for this instant, or null.
  String? get lid => _lid;

  /// Milliseconds into the sprite's current motion: whole steps of its work
  /// frames (or the borrowed baton's), or of the return wave.
  int get t {
    final d = spriteDef;
    if (d == null) return 0;
    if (mood == DaemonMood.back) return _backT;
    if (mood != DaemonMood.work) return 0;
    final last = versionIndex == roster.rules.versions.length - 1;
    return _step * (last ? d.workMs : 130);
  }

  /// The same steps for the portrait's moving parts, one frame each.
  int get portraitT {
    final d = def;
    if (d == null || mood != DaemonMood.work) return 0;
    final ms = d.parts.values.firstOrNull?.ms ?? d.workMs;
    return _step * ms;
  }

  /// How many work steps have been taken since agents started working.
  int get steps => _step;

  /// An egg waiting in the nest as one line: ready (`p4`), blinking when a
  /// daemon would (`rules.eggLine`).
  String eggLineFor(ZooEgg egg, {String? lid}) =>
      eggLine(roster, egg.kind, 'p4', lid: lid);

  /// The egg the slot shows before the first hatch: the one nearest to
  /// hatching (a waiting one, else the one being earned furthest along).
  ZooEggProgress? get nearestEgg => zoo.nearestEgg;

  /// Where the hatch reveal is, as the slot shows it: `rock`, `burst`,
  /// `tumble`, `open`, then `hatchling` (its 0.1 sprite between the halves).
  String? _revealStage;
  String _revealKind = 'first';
  String _revealSprite = '';

  /// The reveal moved on: the slot follows it (`rules.eggLine`).
  void revealAt(String stage, {String? kind, String? sprite}) {
    if (_disposed || !_revealing) return;
    _revealStage = stage;
    if (kind != null) _revealKind = kind;
    if (sprite != null) _revealSprite = sprite;
    _update(force: true);
  }

  /// Eggs waiting to be hatched.
  int get eggsWaiting => zoo.zoo.eggs.length;

  /// Finished turns since you last looked: the brain's count, across every
  /// machine, when there is one; the window's own otherwise.
  int get doneCount => _brainDone ?? _doneCount;

  /// The last few that finished, as lines (`api@office finished: ...`).
  List<String> get doneLast => _doneLast;

  /// Machines asleep, out of reach or otherwise not there.
  List<DaemonMachine> get away => _away;

  /// The slot shows the daemon itself (not a new egg's moment in the nest).
  bool get showsDaemon => def != null && !_showsArrival;

  /// The same egg already chosen by the face, as an art-independent state.
  /// The hatchling's identity remains withheld until the reveal completes.
  (String, String)? get eggArtwork {
    if (!visible || showsDaemon) return null;
    if (_revealing) return (_revealKind, _revealStage ?? 'p4');
    if (_showsArrival) return (_arriving!.kind, 'p4');
    final egg = nearestEgg;
    return egg == null ? null : (egg.kind, egg.stage);
  }

  bool get _showsArrival =>
      _arriving != null && mood != DaemonMood.need && mood != DaemonMood.boop;

  /// The sprite or egg for the status slot (at most eight cells): the
  /// paired individual's one line (render.mjs `renderIndividualSprite`), or
  /// the egg nearest to hatching at its stage (`eggLine`), or, while a hatch
  /// reveal runs, the egg as it opens.
  String get glyph {
    if (!visible) return '';
    final d = spriteDef;
    if (d == null) {
      if (_revealing) {
        return eggLine(
          roster,
          _revealKind,
          _revealStage ?? 'p4',
          lid: _lid,
          sprite: _revealSprite,
        );
      }
      final egg = nearestEgg;
      if (egg == null) return '';
      return eggLine(roster, egg.kind, egg.stage, lid: _lid);
    }
    // A new egg sits in the nest for a moment, unless something needs you.
    if (_showsArrival) return eggLineFor(_arriving!, lid: _lid);
    return renderSprite(
      roster,
      d,
      versionIndex,
      mood,
      t: t,
      lid: _lid,
      motion: motionEnabled,
    );
  }

  /// The slot's ten cells, exactly: the glyph centred on the version's base
  /// sprite (so a baton or a nap's `z` never moves the face), a gutter each
  /// side (a borrowed baton may run into the right one), and a shiny daemon's
  /// `*` in the left gutter.
  String get cell {
    final g = glyph;
    if (g.isEmpty) return '';
    final d = spriteDef;
    final daemonShown = d != null && !_showsArrival;
    final c = statusCell(
      roster,
      g,
      daemonShown ? baseWidth(roster, d, versionIndex) : null,
    );
    return daemonShown && shiny ? '*${c.substring(1)}' : c;
  }

  /// `tim: bell in codex@office: run the migration?` while it speaks; a line
  /// from the pair brain exactly as sent (`[y/n/g] api@office: npm test`).
  String? get voice => _voice.value;

  /// Only the spoken line, for what swaps the status line's context: it does
  /// not change on every work frame.
  ValueListenable<String?> get voiceLine => _voice;

  /// Whether the line being spoken is an alert (needs you, failed): the
  /// message yellow. Otherwise it is a reply, in the status line's own ink.
  bool get voiceAlert => _spoken?.kind.yellow ?? false;

  /// The brain's answers offered with the line being spoken: `[y] [n]`.
  List<DaemonAction> get voiceActions => _spoken?.actions ?? const [];

  /// The brain's id for the line being spoken, to answer it.
  String? get voiceSayId => _spoken?.sayId;

  /// The harness the line being spoken is about (its `[g]` opens it).
  DaemonAbout? get voiceTarget => _spoken?.target;

  /// What a key on the line being spoken would do, in full: shown under it
  /// before its keys arm.
  String? get voiceDetail => _spoken?.detail;

  /// The harness the line being spoken names, by name and machine.
  DaemonHarness? get voiceHarness => _spoken?.harness;

  /// The pair harness wrote the line being spoken (drawn as it speaking).
  bool get voiceFromPair => _spoken?.fromPair ?? false;

  /// The line being spoken waits for a yes to a setting: its keys are
  /// `daemon_confirm`.
  ({String kind, String nonce})? get voiceConfirm => _spoken?.confirm;

  /// The level the daemon acts at, as harnessd says; null without a brain.
  String? get autonomy => _autonomy;

  /// A higher level the zoo asks for, waiting for the person's yes.
  String? get autonomyRequested => _autonomyRequested;

  static const moodWords = {
    DaemonMood.idle: 'content',
    DaemonMood.work: 'agents working',
    DaemonMood.need: 'a harness needs you',
    DaemonMood.done: 'a turn finished',
    DaemonMood.fail: 'something failed',
    DaemonMood.back: 'welcome back',
    DaemonMood.nap: 'napping',
    DaemonMood.boop: 'booped',
  };

  String get label {
    if (_revealing) return 'Hatching';
    if (def != null) return name;
    return eggReady ? 'Egg, ready to hatch' : 'Egg';
  }

  String get detail {
    if (_revealing) return 'Hatching';
    final d = def;
    if (d != null) {
      final eggs = eggsWaiting;
      final done = doneCount;
      return '${d.id} ${daemon!.version}, ${moodWords[mood]}'
          '${done == 0 ? '' : ', $done finished since you looked'}'
          '${eggs == 0 ? '' : ', $eggs ${eggs == 1 ? 'egg' : 'eggs'} waiting'}';
    }
    if (eggReady) {
      return eggsWaiting > 1
          ? 'Ready to hatch, $eggsWaiting eggs'
          : 'Ready to hatch';
    }
    return '${zoo.habitsCounted} of ${zoo.habitsNeeded} habits';
  }

  String get tooltip {
    if (_revealing) return 'Hatching...';
    final d = def;
    if (d != null) {
      final eggs = zoo.zoo.eggs;
      final done = doneCount;
      return [
        '$name · ${moodWords[mood]}',
        '${d.id} ${daemon!.version}',
        if (done > 0)
          '+$done: ${done == 1 ? 'a turn' : 'turns'} finished '
              'since you looked',
        if (done > 0)
          for (final line in _doneLast.take(3)) '  $line',
        if (eggs.isNotEmpty)
          '${eggLineFor(eggs.first)} x${eggs.length} waiting. Click to open.',
        for (final machine in _away)
          daemonMachineLine(machine.name, machine.status),
        // Above `suggest` it acts on its own for you: always said.
        if (daemonAutonomyAboveSuggest(_autonomy))
          'autonomy: ${daemonAutonomyLabel(_autonomy!)}',
        if (_autonomyRequested case final asked? when asked != _autonomy)
          'asks for ${daemonAutonomyLabel(asked)}: waiting for your yes',
        if (quiet) 'Quiet: it says nothing until you turn Quiet off.',
      ].join('\n');
    }
    if (eggReady) {
      final egg = zoo.readyEgg!;
      return eggsWaiting > 1
          ? '${eggLineFor(egg)} x$eggsWaiting. Your egg is ready. '
                'Click to hatch it.'
          : 'Your egg is ready. Click to hatch it.';
    }
    final egg = nearestEgg;
    if (egg != null && egg.kind != 'first') {
      return 'A ${eggName(egg.kind)} is on its way: ${egg.done} of '
          '${egg.need}.\nClick to see your eggs.';
    }
    return 'A daemon is incubating: ${zoo.habitsCounted} of '
        '${zoo.habitsNeeded} habits.\n${_capital(zoo.firstEggRule)}.\n'
        'Click to see them.';
  }

  static String _capital(String s) =>
      s.isEmpty ? s : '${s[0].toUpperCase()}${s.substring(1)}';

  // ── lines ──────────────────────────────────────────────────────────────────

  /// What the window knows right now for a line's slots.
  Map<String, String?> slotsFor(DaemonMood mood, [DaemonSubject? subject]) {
    final about =
        subject ??
        switch (mood) {
          DaemonMood.need => _needs.values.firstOrNull,
          DaemonMood.fail => _failed.firstOrNull,
          _ => null,
        };
    return {
      'who': slotValue(about?.who, limit: 32),
      'q': slotValue(about?.q, limit: 48),
      'recap': slotValue(about?.recap, limit: 60),
      'n': switch (mood) {
        DaemonMood.work => _workingCount > 0 ? '$_workingCount' : null,
        DaemonMood.need => _needIds.isEmpty ? null : '${_needIds.length}',
        DaemonMood.idle => '$_idleCount',
        DaemonMood.fail =>
          _failed.isNotEmpty
              ? '${_failed.length}'
              : subject != null
              ? '1'
              : null,
        DaemonMood.done => doneCount > 0 ? '$doneCount' : null,
        _ => null,
      },
      'summary': mood == DaemonMood.back ? _summary() : null,
    };
  }

  /// The brief's facts, as far as this window knows them:
  /// `2 done, 1 waiting 40m`. Null when there are none.
  String? _summary() {
    final waiting = _needIds.length;
    DateTime? oldest;
    for (final need in _needs.values) {
      final since = need.since;
      if (since != null && (oldest == null || since.isBefore(oldest))) {
        oldest = since;
      }
    }
    final parts = [
      if (_doneWhileAway > 0) '$_doneWhileAway done',
      if (waiting > 0)
        '$waiting waiting'
            '${oldest == null ? '' : ' ${_age(_now().difference(oldest))}'}',
    ];
    return parts.isEmpty ? null : parts.join(', ');
  }

  static String _age(Duration d) => d.inHours >= 1
      ? '${d.inHours}h'
      : d.inMinutes >= 1
      ? '${d.inMinutes}m'
      : '${d.inSeconds}s';

  /// The line for [mood] now, for the panel: filled from what is known, the
  /// roster's example while nothing is going on, never a made-up fact.
  String currentLine(DaemonMood mood) {
    final d = def;
    if (d == null) return '';
    final values = slotsFor(mood);
    return mood == DaemonMood.idle
        ? daemonPreviewLine(d, mood, values)
        : daemonLine(d, mood, values);
  }

  // ── inputs ─────────────────────────────────────────────────────────────────

  void setEnvironment({required bool foreground, required bool reduceMotion}) {
    if (_disposed) return;
    final was = _foreground;
    final changed = _foreground != foreground || _reduceMotion != reduceMotion;
    _foreground = foreground;
    _reduceMotion = reduceMotion;
    if (!changed) return;
    if (!foreground) {
      if (_awayAt == null) {
        _awayAt = _now();
        _doneWhileAway = 0;
      }
      _seenTimer?.cancel();
      _seenTimer = null;
      _stopBlink();
    } else if (!was) {
      final away = _awayAt;
      _awayAt = null;
      if (away != null && _now().difference(away) >= backAfter) {
        _back();
      } else {
        look(force: true);
      }
      // Back at the window: finished turns are seen after a moment in front.
      _seenTimer?.cancel();
      _seenTimer = doneCount == 0
          ? null
          : Timer(seenAfterFocus, () {
              _seenTimer = null;
              if (_foreground) seen();
            });
    }
    if (!motionEnabled) _stopBlink();
    _update(force: true);
  }

  void sync(DaemonWatch watch) {
    if (_disposed) return;
    final before = mood;
    final newNeeds = watch.needIds.difference(_heardNeeds);
    final finished = _newEnds(_turns, watch.turns, watch.ended, failed: false);
    final failed = _newEnds(_fails, watch.fails, watch.ended, failed: true);
    _working = watch.working;
    _workingCount = watch.workingCount;
    _failing = watch.failing;
    _failed = watch.failed;
    _needIds = watch.needIds;
    _needs = watch.needs;
    _idleCount = watch.idleCount;
    final awayChanged =
        watch.away.length != _away.length ||
        [
          for (var i = 0; i < _away.length; i++)
            watch.away[i].name != _away[i].name ||
                watch.away[i].status != _away[i].status,
        ].any((changed) => changed);
    _away = watch.away;
    final countsChanged =
        watch.asks != _asks ||
        watch.doneCount != _brainDone ||
        !listEquals(watch.doneLast, _doneLast);
    final dialChanged =
        watch.autonomy != _autonomy ||
        watch.autonomyRequested != _autonomyRequested;
    _autonomy = watch.autonomy;
    _autonomyRequested = watch.autonomyRequested;
    _asks = watch.asks;
    _brainDone = watch.doneCount;
    _doneLast = watch.doneLast;
    final focusChanged = watch.focus != _focus;
    _focus = watch.focus;
    _heardNeeds.addAll(watch.needIds);
    if (_heardNeeds.length > 512) _heardNeeds.retainAll(watch.needIds);
    if (focusChanged) {
      // A pane switch is a pause in thought: a waiting line may speak now.
      // A line about the pane you just switched to has done its job.
      if (_spoken?.about != null && _spoken!.about == _focus) _silence();
      _lastKey = null;
      if (_pendingVoice != null) _trySpeak();
    }
    // Restored state, imported history and reconnects are baselines.
    if (!_baselined || def == null) {
      _baselined = def != null;
      _update(
        before: before,
        force: awayChanged || countsChanged || dialChanged,
      );
      return;
    }
    final d = def!;
    if (newNeeds.isNotEmpty) {
      _napUntil = null;
      _napTimer?.cancel();
      _blink('ack', delay: const Duration(milliseconds: 160));
      // About a harness you are not looking at, if there is one.
      final id = newNeeds.firstWhere(
        (id) => _aboutOf(id) != _focus,
        orElse: () => newNeeds.first,
      );
      final subject = _needs[id];
      _say(
        daemonLine(d, DaemonMood.need, slotsFor(DaemonMood.need, subject)),
        mood: DaemonMood.need,
        kind: _LineKind.alert,
        about: subject?.key ?? _aboutOf(id),
      );
    }
    if (failed.isNotEmpty) {
      _hold(DaemonMood.fail);
      _blink('ack', delay: const Duration(milliseconds: 160));
      final subject = failed.whereType<DaemonSubject>().lastOrNull;
      if (newNeeds.isEmpty) {
        _say(
          daemonLine(d, DaemonMood.fail, slotsFor(DaemonMood.fail, subject)),
          mood: DaemonMood.fail,
          kind: _LineKind.alert,
          about: subject?.key,
        );
      }
    } else if (finished.isNotEmpty) {
      _blink('ack', delay: const Duration(milliseconds: 160));
      // Finished turns are a count beside the slot, never a line; the pane
      // in front of you is already seen.
      final unseen = finished.where((s) => s == null || s.key != _focus);
      _doneCount += unseen.length;
      if (!_foreground) _doneWhileAway += unseen.length;
      final now = _now();
      if (_lastDone == null || now.difference(_lastDone!) >= doneCooldown) {
        _lastDone = now;
        _hold(DaemonMood.done);
      }
    }
    _update(
      before: before,
      force: finished.isNotEmpty || awayChanged || countsChanged || dialChanged,
    );
  }

  static String _aboutOf(String needId) {
    final hash = needId.indexOf('#');
    return hash < 0 ? needId : needId.substring(0, hash);
  }

  /// The turns that ended since the last count, one entry each: who they
  /// were when the window knows (newest last), null when it does not.
  static List<DaemonSubject?> _newEnds(
    Map<String, int> seen,
    Map<String, int> now,
    Map<String, List<DaemonTurnEnd>> ended, {
    required bool failed,
  }) {
    final out = <DaemonSubject?>[];
    for (final entry in now.entries) {
      final previous = seen[entry.key];
      seen[entry.key] = entry.value;
      if (previous == null || entry.value <= previous) continue;
      final count = entry.value - previous;
      final known = [
        for (final end in ended[entry.key] ?? const <DaemonTurnEnd>[])
          if (end.failed == failed) end.subject,
      ];
      final recent = known.length > count
          ? known.sublist(known.length - count)
          : known;
      out
        ..addAll(List<DaemonSubject?>.filled(count - recent.length, null))
        ..addAll(recent);
    }
    return out;
  }

  /// A real agent event (a tool starting, output arriving, a turn starting
  /// or ending): the work frame steps once, at most twice a second (four
  /// times for a fidgety individual).
  void pulse() {
    if (_disposed ||
        def == null ||
        !motionEnabled ||
        mood != DaemonMood.work ||
        _stepTimer != null) {
      return;
    }
    final since = _lastStep == null ? null : _now().difference(_lastStep!);
    final every = stepInterval;
    if (since == null || since >= every) {
      _advance();
      return;
    }
    _stepTimer = Timer(every - since, () {
      _stepTimer = null;
      _advance();
    });
  }

  void _advance() {
    if (_disposed || def == null || !motionEnabled || mood != DaemonMood.work) {
      return;
    }
    _step++;
    _lastStep = _now();
    _lastGlyph = glyph;
    notifyListeners();
  }

  /// A key went down somewhere in the window. Enter ends a thought: a line
  /// waiting for you may speak now. Any other key holds it for 8 s more.
  void noteKey({bool enter = false}) {
    if (enter) {
      _lastKey = null;
      if (_pendingVoice != null) _trySpeak();
    } else {
      _lastKey = _now();
    }
  }

  /// You looked at the slot (hover, its panel, the window coming back): the
  /// tally of finished turns has been seen, here and by the brain.
  void seen() {
    if (_disposed || doneCount == 0) return;
    _doneCount = 0;
    if ((_brainDone ?? 0) > 0) {
      _brainDone = 0;
      onSeen?.call();
    }
    notifyListeners();
  }

  /// A click on the daemon.
  void boop() {
    if (_disposed || def == null) return;
    wake(notify: false);
    _booped = true;
    _boopTimer?.cancel();
    _boopTimer = Timer(roster.rules.hold(DaemonMood.boop), () {
      _booped = false;
      _update(force: true);
    });
    _say(
      def!.line(DaemonMood.boop),
      mood: DaemonMood.boop,
      kind: _LineKind.reply,
    );
    _update(force: true);
  }

  /// "I see you": hover, its panel opening, the window coming back.
  void look({bool force = false}) {
    if (_disposed || !_blinks) return;
    final now = _now();
    if (_lastLook != null && now.difference(_lastLook!) < lookEvery) return;
    _lastLook = now;
    _blink('look', delay: force ? const Duration(milliseconds: 250) : null);
  }

  void nap() {
    if (_disposed || def == null) return;
    _napUntil = _now().add(napLength);
    _napTimer?.cancel();
    _napTimer = Timer(napLength, () => wake());
    _update(force: true);
  }

  void wake({bool notify = true}) {
    if (_napUntil == null) return;
    _napUntil = null;
    _napTimer?.cancel();
    _napTimer = null;
    if (notify) _update(force: true);
  }

  /// The hatch reveal is running: the status slot keeps the egg and nothing
  /// names the hatchling until [endReveal].
  void beginReveal({String? kind}) {
    if (_disposed || _revealing) return;
    _revealing = true;
    _revealStage = null;
    _revealKind = kind ?? zoo.readyEgg?.kind ?? 'first';
    _revealSprite = '';
    _update(force: true);
  }

  /// The reveal finished or was dismissed. The daemon arrives and says its
  /// first words, with a slow blink: they have just met.
  void endReveal() {
    if (_disposed || !_revealing) return;
    _revealing = false;
    _revealStage = null;
    _baselined = false;
    final d = def;
    if (d != null) {
      _pairKey = daemon?.uid;
      _blink('slow', delay: const Duration(milliseconds: 300));
      _say(d.first, mood: null, kind: _LineKind.reply);
    }
    _update(force: true);
  }

  void _zooChanged() {
    if (_disposed) return;
    final key = daemon?.uid;
    if (key != _pairKey) {
      // A different pair: what it watches starts again from a baseline.
      _pairKey = key;
      _baselined = false;
      _held = null;
      _holdTimer?.cancel();
    }
    _update(force: true);
  }

  void _settingsChanged() {
    if (_disposed) return;
    if (settings.quiet) {
      _pendingVoice = null;
      _pendingTimer?.cancel();
      _silence();
    }
    if (!motionEnabled) _stopBlink();
    _update(force: true);
  }

  /// A new egg or a level-up, here or on another client. Neither is a line:
  /// the egg waits after the slot (`1 egg`) until it is opened, and a
  /// level-up is a slow blink.
  void _zooEvent(ZooEvent event) {
    if (_disposed) return;
    final d = def;
    switch (event) {
      case ZooEggArrived(:final egg):
        // Before the first hatch the slot already shows the egg itself.
        if (d == null) return;
        _arriving = egg;
        _arrivingTimer?.cancel();
        _arrivingTimer = Timer(eggShowFor, () {
          _arriving = null;
          _update(force: true);
        });
        _blink('ack', delay: const Duration(milliseconds: 160));
        _update(force: true);
      case ZooDaemonHatched(:final daemon):
        if (daemon.uid == this.daemon?.uid &&
            !revealing &&
            !quiet &&
            motionEnabled &&
            !napping &&
            mood != DaemonMood.need) {
          _hold(DaemonMood.done);
          _update(force: true);
        }
      case ZooDaemonGrew(:final daemon, :final versionChanged):
        if (d == null || daemon.uid != this.daemon?.uid) return;
        if (versionChanged &&
            !quiet &&
            motionEnabled &&
            !napping &&
            mood != DaemonMood.need) {
          _hold(DaemonMood.done);
        }
        // A bond-only increase remains a slow blink.
        _blink('slow', delay: const Duration(milliseconds: 200));
        _update(force: true);
    }
  }

  // ── reactions ──────────────────────────────────────────────────────────────

  void _hold(DaemonMood held) {
    _held = held;
    _holdTimer?.cancel();
    _holdTimer = Timer(roster.rules.hold(held), () {
      _held = null;
      _update(force: true);
    });
  }

  /// Back after 15 minutes or more: it waves and blinks slowly. The brief
  /// (or the panel) carries the facts; no line takes over the status line.
  void _back() {
    if (def == null || _needIds.isNotEmpty || napping) return;
    _hold(DaemonMood.back);
    _blink(
      'slow',
      delay:
          roster.rules.hold(DaemonMood.back) +
          const Duration(milliseconds: 120),
    );
  }

  /// Whether the slot shows something that blinks: the daemon, or a ready
  /// egg (its eyes peek from the chip).
  bool get _blinks =>
      def != null ||
      (_revealing
          ? (_revealStage ?? 'p4') == 'p4' || _revealStage == 'rock'
          : nearestEgg?.ready == true);

  void _blink(String kind, {Duration? delay}) {
    final steps = roster.rules.blinks[kind];
    if (steps == null || !motionEnabled || !_blinks) return;
    _stopBlink();
    var index = 0;
    void step() {
      if (_disposed) return;
      if (index >= steps.length || !motionEnabled) {
        _lid = null;
        _blinkTimer = null;
        notifyListeners();
        return;
      }
      final (lid, ms) = steps[index++];
      // No blinks while working, napping or booped.
      _lid = roster.rules.noBlinkMoods.contains(mood.name) ? null : lid;
      notifyListeners();
      _blinkTimer = Timer(Duration(milliseconds: ms), step);
    }

    if (delay == null || delay == Duration.zero) {
      step();
    } else {
      _blinkTimer = Timer(delay, step);
    }
  }

  void _stopBlink() {
    _blinkTimer?.cancel();
    _blinkTimer = null;
    _lid = null;
  }

  // ── voice ──────────────────────────────────────────────────────────────────

  void _say(
    String line, {
    required DaemonMood? mood,
    required _LineKind kind,
    String? about,
  }) {
    if (line.isEmpty || quiet) return;
    _dropExpired();
    // A reply never pushes aside an alert waiting to be said.
    if (kind == _LineKind.reply && (_pendingVoice?.kind.unsolicited ?? false)) {
      return;
    }
    final now = _now();
    // With a brain, a roster alert waits a moment for the brain's own words.
    final waits = brainActive && kind == _LineKind.alert;
    _pendingVoice = _Line(
      line,
      at: now,
      mood: mood,
      kind: kind,
      about: about,
      holdUntil: waits ? now.add(brainWait) : null,
    );
    _trySpeak();
  }

  /// The brain's line (`daemon_say`), shown exactly as sent, keys first, for
  /// its `ttlMs`. `need` and `fail` take over the status line in yellow like
  /// the window's own alerts; `ask` (the pair wants your key) is yellow and at
  /// once; `say` (the pair answering you) is a dim reply; `auto` (a rule or
  /// the pair acted) is dim, and the face shows it as done. A finished turn
  /// or a return is never a line (the expression and brief carry them). A
  /// second line with the same id replaces it in place, with the time the
  /// brain says it has left.
  void sayFromBrain(DaemonSay say) {
    if (_disposed || def == null) return;
    final mood = say.mood;
    if (mood == DaemonSayMood.auto) {
      // It did something on its own: a moment of `done`, and an ack.
      _hold(DaemonMood.done);
      _blink('ack', delay: const Duration(milliseconds: 160));
      _update(force: true);
    }
    if (quiet) return;
    _dropExpired();
    final kind = switch (mood) {
      DaemonSayMood.need || DaemonSayMood.fail => _LineKind.alert,
      DaemonSayMood.ask => _LineKind.ask,
      DaemonSayMood.auto => _LineKind.report,
      DaemonSayMood.say => _LineKind.reply,
      // An older brain's line with answers still needs you.
      _ when say.actions.isNotEmpty => _LineKind.alert,
      _ => null,
    };
    if (kind == null) return;
    final line = _Line(
      say.line,
      at: _now(),
      mood: mood?.face,
      kind: kind,
      about: say.aboutKey,
      sayId: say.id,
      target: say.about?.key == null ? null : say.about,
      actions: say.actions,
      ttl: say.ttl ?? voiceFor,
      exact: true,
      detail: say.detail,
      harness: say.harness,
      fromPair: say.fromPair,
      confirm: say.confirm,
    );
    final spoken = _spoken;
    // The same line again (the model's better words): in place.
    if (spoken != null && spoken.sayId == say.id) {
      _show(line, countsAsUnsolicited: false);
      return;
    }
    if (_pendingVoice?.sayId == say.id) {
      _pendingVoice = line;
      _trySpeak();
      return;
    }
    // A roster alert about the same harness is replaced by the brain's words.
    if (spoken != null &&
        spoken.kind == _LineKind.alert &&
        spoken.sayId == null &&
        line.about != null &&
        spoken.about == line.about) {
      _show(line, countsAsUnsolicited: false);
      return;
    }
    // A reply never pushes aside an alert waiting to be said (the talk keeps
    // it in the panel). A proposal does: its keys work only while it shows,
    // and the need it displaces stays on the face and in the panel.
    if (kind == _LineKind.reply && (_pendingVoice?.kind.unsolicited ?? false)) {
      return;
    }
    _pendingVoice = line;
    _trySpeak();
  }

  /// A line still waiting whose time ran out while it waited is gone.
  void _dropExpired() {
    final pending = _pendingVoice;
    if (pending != null &&
        _now().difference(pending.at) >= (pending.ttl ?? voiceExpires)) {
      _pendingVoice = null;
      _pendingTimer?.cancel();
      _pendingTimer = null;
    }
  }

  /// A line of the window's own, such as why an answer did not go through.
  void sayNote(String line) {
    if (_disposed || def == null) return;
    _say(line, mood: null, kind: _LineKind.reply);
  }

  /// `daemon_unsay`: answered elsewhere, gone, done or stale.
  void unsay(String id) {
    if (_pendingVoice?.sayId == id) _pendingVoice = null;
    if (_spoken?.sayId == id) _silence();
  }

  /// Escape: the line goes.
  void dismissVoice() => _silence();

  /// You answered the line: it goes, and since you are already with the
  /// daemon, the next question may follow without the two-minute wait.
  void answered() {
    _lastUnsolicited = null;
    _silence();
  }

  void _silence() {
    _voiceTimer?.cancel();
    _voiceTimer = null;
    _spoken = null;
    if (_voice.value == null) return;
    _voice.value = null;
    if (!_disposed) notifyListeners();
  }

  void _trySpeak() {
    _pendingTimer?.cancel();
    _pendingTimer = null;
    final pending = _pendingVoice;
    if (pending == null || _disposed) return;
    final now = _now();
    final unsolicited = pending.kind.unsolicited;
    final stale =
        now.difference(pending.at) >= (pending.ttl ?? voiceExpires) ||
        (pending.mood == DaemonMood.need &&
            pending.sayId == null &&
            _needIds.isEmpty) ||
        def == null ||
        quiet ||
        // Nothing about the pane in front of you.
        (pending.about != null && pending.about == _focus) ||
        // A nap keeps it quiet, except for what needs you.
        (napping && pending.mood != DaemonMood.need && unsolicited) ||
        // At most one line nobody asked for every two minutes.
        (unsolicited &&
            _lastUnsolicited != null &&
            now.difference(_lastUnsolicited!) < unsolicitedEvery);
    if (stale) {
      _pendingVoice = null;
      return;
    }
    Duration? wait;
    if (pending.holdUntil case final until? when now.isBefore(until)) {
      wait = until.difference(now);
    } else if (_lastKey case final key?
        when unsolicited && now.difference(key) < typingQuiet) {
      // Never mid-thought: after Enter, a pane switch or 8 s without a key.
      wait = typingQuiet - now.difference(key);
    } else if ((pending.kind != _LineKind.ask && dialogOpen()) ||
        !_foreground) {
      wait = const Duration(milliseconds: 500);
    }
    if (wait != null) {
      _pendingTimer = Timer(wait, _trySpeak);
      return;
    }
    _pendingVoice = null;
    _show(pending, countsAsUnsolicited: unsolicited);
  }

  void _show(_Line line, {required bool countsAsUnsolicited}) {
    // A brain line's keys work only while the brain still holds it: it shows
    // for what is left of its `ttlMs` since it arrived.
    final showFor = line.sayId != null
        ? (line.ttl ?? voiceFor) - _now().difference(line.at)
        : line.actions.isEmpty
        ? voiceFor
        : line.ttl ?? askFor;
    if (showFor <= Duration.zero) return;
    _spoken = line;
    if (countsAsUnsolicited) _lastUnsolicited = _now();
    _voice.value = line.exact ? line.line : '$name: ${line.line}';
    _voiceTimer?.cancel();
    _voiceTimer = Timer(showFor, _silence);
    notifyListeners();
  }

  // ── frames ─────────────────────────────────────────────────────────────────

  DaemonMood? _lastMood;
  String? _lastGlyph;

  void _update({DaemonMood? before, bool force = false}) {
    if (_disposed) return;
    final now = mood;
    _runMotion(now);
    final glyph = this.glyph;
    if (force || now != (before ?? _lastMood) || glyph != _lastGlyph) {
      _lastMood = now;
      _lastGlyph = glyph;
      notifyListeners();
    }
  }

  void _runMotion(DaemonMood now) {
    final d = def;
    final artKey = '${daemon?.uid}:${now.name}';
    final animated =
        animateIllustrations &&
        d != null &&
        illustratedStyles.containsKey(d.id) &&
        motionEnabled &&
        !quiet &&
        now != DaemonMood.work &&
        now != DaemonMood.fail;
    if (!animated || artKey != _artKey) {
      _artTimer?.cancel();
      _artTimer = null;
      _artFrame = 0;
      _artKey = artKey;
    }
    final finite =
        now == DaemonMood.done ||
        now == DaemonMood.boop ||
        now == DaemonMood.back;
    if (animated && _artTimer == null && (!finite || _artFrame < 3)) {
      final index = const [
        'idle',
        'work',
        'need',
        'done',
        'fail',
        'nap',
        'boop',
      ].indexOf(now == DaemonMood.back ? 'done' : now.name);
      final timing = illustratedStyles[d.id]!['timing'] as List;
      _artTimer = Timer.periodic(
        Duration(
          milliseconds: index < 0 ? 190 : (timing[index] as int).clamp(80, 600),
        ),
        (_) {
          if (_disposed) return;
          _artFrame = finite
              ? (_artFrame + 1).clamp(0, 3)
              : (_artFrame + 1) % 4;
          if (finite && _artFrame == 3) {
            _artTimer?.cancel();
            _artTimer = null;
          }
          notifyListeners();
        },
      );
    }
    // Work frames step only on agent events; leaving work puts them at rest.
    if (d == null || !motionEnabled || now != DaemonMood.work) {
      _stepTimer?.cancel();
      _stepTimer = null;
      _step = 0;
      _lastStep = null;
    }
    // The return wave is finite: it runs while `back` is held.
    final waving = d != null && motionEnabled && now == DaemonMood.back;
    if (!waving) {
      _backTimer?.cancel();
      _backTimer = null;
      _backT = 0;
      return;
    }
    if (_backTimer != null) return;
    final last = versionIndex == roster.rules.versions.length - 1;
    final ms = last ? roster.rules.backFrameMs : 130;
    _backTimer = Timer.periodic(Duration(milliseconds: ms), (_) {
      if (_disposed) return;
      _backT += ms;
      final glyph = this.glyph;
      if (glyph != _lastGlyph) {
        _lastGlyph = glyph;
        notifyListeners();
      }
    });
  }

  @override
  void dispose() {
    _disposed = true;
    zoo.removeListener(_zooChanged);
    settings.removeListener(_settingsChanged);
    if (_ownsSettings) settings.dispose();
    unawaited(_events.cancel());
    for (final timer in [
      _arrivingTimer,
      _holdTimer,
      _boopTimer,
      _napTimer,
      _blinkTimer,
      _stepTimer,
      _backTimer,
      _artTimer,
      _voiceTimer,
      _pendingTimer,
      _seenTimer,
    ]) {
      timer?.cancel();
    }
    _voice.dispose();
    super.dispose();
  }
}

class _Line {
  const _Line(
    this.line, {
    required this.at,
    required this.kind,
    this.mood,
    this.about,
    this.sayId,
    this.actions = const [],
    this.ttl,
    this.holdUntil,
    this.exact = false,
    this.target,
    this.detail,
    this.harness,
    this.fromPair = false,
    this.confirm,
  });
  final String line;
  final DateTime at;
  final _LineKind kind;
  final DaemonMood? mood;

  /// Shown exactly as sent (the brain's line, keys first), not as
  /// `name: line`.
  final bool exact;

  /// The harness a brain line is about.
  final DaemonAbout? target;

  /// `machineId/agentId` of the harness it is about, when it is about one.
  final String? about;
  final String? sayId;
  final List<DaemonAction> actions;
  final Duration? ttl;

  /// A roster line waiting for the brain's words until then.
  final DateTime? holdUntil;

  /// A brain line's full `detail`, the harness it names, whether the pair
  /// harness wrote it, and the setting it waits on.
  final String? detail;
  final DaemonHarness? harness;
  final bool fromPair;
  final ({String kind, String nonce})? confirm;
}