+ends with them, and a change applies at the next call. The agent can
+propose a change to the file, and it makes the change only after the
+user agrees.
+
+A permanent child agent lives in ``agent/children/NAME/`` with the same
+files as the root. Create its directory and ``config.json`` by hand
+before startup. Use the root config fields with a separate random ID,
+set ``name`` to ``NAME``, and add ``parent`` with the root name and
+``responsibility`` with the child's area. The daemon opens all children
+at startup. A missing or invalid child config stops startup. Only one
+level of children is supported.
+
+Each child has its own memory, model client, usage file, subagents,
+schedules, and turn loop. Its prompt limits work to its area, asks for
+only reports that need the parent or the user, and permits an empty
+reply. Children have no WhatsApp tools and draft replies instead of
+sending them. Clients and WhatsApp still address only the root. A
+child's saved schedules and subagents can resume at startup. The ready
+log line lists the child names.
+
+A message from a parent to its own child enters the child's log as
+``user`` and wakes it. A child's final reply reaches the parent as
+``work`` with the prefix ``[NAME] `` and wakes it. An empty reply sends
+nothing. A busy recipient takes the message between tool calls or in its
+next turn. ``agent/messages.json``, with mode 0600, keeps messages until
+their recipient finishes its turn. A daemon stop preserves queued
+messages and reports for the next start without a second log entry. An
+interrupted turn can repeat its model calls and tools after restart.
+Backups lock this queue with the agent files. No tools send messages
+between parent and child agents yet.
+
+**************
+ User service
+**************
+
+The Nix package includes ``share/systemd/user/onechat.service``. It runs
+``onechat daemon`` from that package, starts at login when enabled, and
+restarts 5 seconds after a failure. A stop sends SIGTERM to the daemon
+and allows up to 120 seconds for cleanup. Its output goes to the user
+journal. The service has the rights of the user, as the terminal daemon
+does.
+
+Build a package with a separate result link. Keep this link so that Nix
+does not collect the package while the service uses it:
+
+.. code:: console
+
+ nix build --out-link result-service
+ systemctl --user link --force "$PWD/result-service/share/systemd/user/onechat.service"
+ systemctl --user edit onechat.service
+
+In the editor, set the data directory with this drop-in. Replace
+``DATA_DIR`` with an absolute path to the data directory. Set the same
+``ONECHAT_DIR`` for each terminal client. Without a drop-in, the data
+directory rules above apply to the environment of the user manager, not
+to the development shell.
+
+.. code:: ini
+
+ [Service]
+ Environment="ONECHAT_DIR=DATA_DIR"
+
+The service does not read the environment of an open terminal. If the
+agent needs tools from a shell, set ``Environment="PATH=TOOLS_PATH"`` in
+the same drop-in, with ``TOOLS_PATH`` replaced by the complete search
+path, including bash. For the API endpoint, use
+``EnvironmentFile=ENV_FILE``, with ``ENV_FILE`` replaced by an absolute
+path to a mode 0600 file that sets ``OPENAI_API_KEY``. Keep secrets out
+of the unit and Nix sources.
+
+Use the existing data directory, or copy the development data before the
+first service start. For a copy, first stop the terminal daemon with
+Ctrl-C and wait for it to exit. Replace ``DATA_DIR`` below with a new,
+empty destination. If the development shell uses a custom
+``ONECHAT_DIR``, replace ``.devenv/onechat`` with that source. Copy the
+whole directory so that ``auth.json``, ``telegram.json``,
+``config.json``, ``agent/``, and ``whatsapp/`` stay together, including
+the WhatsApp session and its database files. The copy preserves the file
+modes and the source as a backup. Do not copy or use the same data from
+two running daemons.
+
+.. code:: console
+
+ install -d -m 0700 DATA_DIR
+ cp -a .devenv/onechat/. DATA_DIR/
+
+After the terminal daemon exits and the data is ready, enable and start
+the service:
+
+.. code:: console
+
+ systemctl --user daemon-reload
+ systemctl --user enable --now onechat.service
+ systemctl --user status onechat.service
+ ONECHAT_DIR=DATA_DIR ./result-service/bin/onechat
+ journalctl --user -u onechat.service -f
+
+After a pull, update the package and unit with:
+
+.. code:: console
+
+ git pull
+ bin/service-update
+
+The script builds with the same ``result-service`` link, reloads the
+user manager, and restarts the service only if it is active. The unit
+link follows ``result-service``, so no new link is needed.
+
+The service starts with the user manager at login, not at boot without a
+login. To stop it, or also remove its start at login:
+
+.. code:: console
+
+ systemctl --user stop onechat.service
+ systemctl --user disable onechat.service
+
+********************
+ Backup and restore
+********************
+
+Back up the running daemon to one mode 0600 ``.tar.gz`` archive. The
+command prints its path and size in bytes. With no daemon, it fails.
+
+.. code:: console
+
+ onechat backup BACKUP_FILE.tar.gz
+ ONECHAT_DIR=EMPTY_DATA_DIR onechat restore BACKUP_FILE.tar.gz
+
+The daemon flushes memory and holds its write locks during the agent
+copy. It also flushes and locks the child agents and all subagent logs.
+It copies the WhatsApp session with SQLite ``VACUUM INTO``, not as raw
+database files. It then compresses the copy and installs the archive
+through a temporary file and a rename. Use a backup path outside the
+data directory.
+
+The archive includes configuration, instructions, the log, tree,
+indexes, views, layout, schedules, subagents, children, Telegram offset,
+tokens, and WhatsApp state and session. It excludes sockets, lock files,
+``probe/``, and the ``agent-backup-*`` import copies. Links and special
+files fail, rather than enter the archive. **The archive holds
+secrets**, including login tokens, the Telegram bot token, and the
+WhatsApp link. Keep it private. There is no encryption or remote copy.
+
+Restore needs a stopped daemon and an empty destination. It checks the
+token lock and validates the archive before it installs files, with
+their modes. It rejects unsafe paths, links, and special files. A failed
+restore can leave ``auth.lock`` in the destination. Use another empty
+directory for a retry. Do not run the source and restored WhatsApp links
+at the same time. Check the restored log and view before you use it in
+place of the source.
+
+For a daily local archive with the last 14 kept, save this script as
+``BACKUP_SCRIPT``. Replace ``BACKUP_DIR`` with a private archive
+directory outside the data directory. Replace ``ONECHAT_BINARY`` with
+the absolute path through the stable ``result-service/bin/onechat``
+package link. Make the archive directory with mode 0700 before you
+enable the timer.
+
+.. code:: sh
+
+ #!/bin/sh
+ set -eu
+ umask 077
+ cd BACKUP_DIR
+ ONECHAT_BINARY backup "onechat-$(date +%F).tar.gz"
+ find . -maxdepth 1 -type f -name 'onechat-????-??-??.tar.gz' -printf '%f\n' |
+ sort -r | tail -n +15 |
+ while IFS= read -r file; do
+ rm -- "$file"
+ done
+
+Save these units as ``onechat-backup.service`` and
+``onechat-backup.timer`` in the systemd user unit directory. Replace
+``DATA_DIR`` and ``BACKUP_SCRIPT`` with absolute paths. The service uses
+the daemon unit from User service above.
+
+.. code:: ini
+
+ [Unit]
+ Description=Back up OneChat data
+ Requires=onechat.service
+ After=onechat.service
+
+ [Service]
+ Type=oneshot
+ Environment="ONECHAT_DIR=DATA_DIR"
+ UMask=0077
+ ExecStart=/bin/sh BACKUP_SCRIPT
+
+.. code:: ini
+
+ [Unit]
+ Description=Back up OneChat each day
+
+ [Timer]
+ OnCalendar=daily
+ Persistent=true
+
+ [Install]
+ WantedBy=timers.target
+
+Enable the timer with the user manager. A failed backup leaves the
+existing archives in place and skips removal of old archives.
+
+.. code:: console
+
+ systemctl --user daemon-reload
+ systemctl --user enable --now onechat-backup.timer
+ systemctl --user list-timers onechat-backup.timer
+
+************
+ Daemon log
+************
+
+The daemon writes short events with the part prefix and ordered
+``key=value`` attributes. An error cause comes last. Normal events use
+info, failures that can be retried or lose nothing use warning, and
+failures that lose data or stop work use error.
+
+With ``JOURNAL_STREAM`` set, each line carries a syslog priority without
+a time stamp or level word. The user journal can show only warnings and
+errors:
+
+.. code:: console
+
+ journalctl --user -u onechat -p warning
+
+The summary warning names its node. A schedule run has ``late`` only
+when it ran late:
+
+.. code:: text
+
+ <4>onechat: summary failed level=0 index=0: fake failure
+ <6>onechat: schedule ran id=1
+ <6>onechat: schedule ran id=2 late=1m0s
+
+Outside the journal, each line starts with the time stamp and level.
projects / onechat / blobdiff