@jungjaehoon/mama-os 0.77.0 → 0.79.0

package/CHANGELOG.md

@@ -5,6 +5,452 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [0.79.0] - 2026-11-01
+
+### Added
+
+- `google.read`: the owner agent reads Gmail, Calendar and Sheets, and a Google Doc, Sheet or
+  Slides file as text, live through `gws`, which the daemon runs with its own sign-in. The agent
+  names the method as gws takes it (`service`, `argv`, `params`); read methods only, and no gws
+  flag is an input, so nothing is sent or uploaded. Each call runs in a directory of its own that
+  is removed after it, and a response gws writes to a file instead of printing (a parameter such
+  as `alt` or `callback` asking for another format) is refused, never left on disk. A list
+  returns one page with its `nextPageToken`; a result over 100,000 characters is refused with how
+  to narrow it. A replay turn cannot use it: Google read now is past the replay's window. A missing `gws`, no sign-in, a sign-in without the service, an API not enabled in
+  the client's Cloud project, and a rate or quota refusal each come back saying what to do. The
+  result is quoted as external evidence and each call is in `tool_traces`. The common session has
+  it in chat, source changes and reports, and an owner-role person in their own DM; members
+  without the role and room sessions do not. Drive files are still found with `drive.read` and
+  fetched with `drive.download`.
+- Closing summaries for finished work. Every hour MAMA orders the work it saw closed or cancelled
+  since its first start with this version, ten items at a time. For each, the agent writes one
+  summary: the rounds, the points of outside feedback, who did what, and how it ended. Then a
+  later question reads one place. The order is checked item by item: a revision from the order's
+  run that leaves a description counts, as does a `work.no_update` naming an item whose summary
+  is already current. A status-only revision does not count. An item that
+  stays unchecked is ordered again, and after three orders it is logged as lost. `work.no_update`
+  can now name work items (`commitmentIds`) as well as observations.
+- A daily board check. Once a day, before the first full report, MAMA orders work items to
+  compare with the board: up to ten open items whose Trello card moved after the item was last
+  revised, and up to ten items in progress or in review with no source event in over 30 days,
+  oldest first. The agent reads each card live and either revises the item with the reason or
+  says why it stays. Each item is checked like the closing summaries. An item that was kept, or
+  given up on after three tries, comes back only after it is revised again. The stale-work step
+  leaves the daily page, since this order now does it.
+- Telegram commands MAMA answers itself, without a model turn, listed in the bot's command menu:
+  `/whoami` (your Telegram ID and whether MAMA knows you as an owner or a member), `/status`
+  (MAMA's version, whether a turn is running in this conversation, what waits; owners, in their
+  own DM, also see every conversation and the sources), `/new` (starts the conversation over;
+  refused while MAMA still works on something of that person's or a message of theirs waits) and
+  `/help`. In the common group an owner's commands act on the common session and a member's on
+  their own group conversation. Unregistered senders still get no answer, a command addressed to
+  another bot is left alone, and any other command goes to MAMA as a message.
+- `mama init` sets up a new install and starts it:
+  - **Checks first, before writing anything:** the backend is installed, at least the verified
+    version, and signed in; Telegram accepts the bot token; the member and tool folders stay
+    outside HOME. Those folders default to a folder of the user's (`Shared/mama-<user>/…` in the Shared folder beside the home folders
+    on macOS, `/var/lib/mama/<user>/…` on Linux), and init refuses one another account owns or can
+    write.
+  - **Sign-in:** init signs nothing in. A backend that is not signed in stops it before anything
+    is written, and init names the login with the backend's full path (`claude auth login`, or
+    `codex login` in MAMA's Codex home, which init creates), for the person's agent to run.
+    `mama init --section model` runs that login on its terminal, and offers the only backend on
+    PATH as the default answer (#539).
+  - **Then in order:** writes the setup, registers the person running it as the first owner,
+    installs the document tools, installs and starts the service through `mama service`, and
+    waits until the daemon reports it is running and the viewer answers `/health`. Last, the
+    daemon runs one real backend turn in a session of its own, so the login is proven as the
+    service runs it; a failure names `mama logs` and `mama doctor`, and the install command run
+    again checks it after a fix.
+  - **Repeat-safe:** a failed run continues from its last finished step.
+    On a finished setup, init says so, names `mama doctor`, `mama service restart` and
+    `mama update`, and exits 0 (#538, #539).
+  - **No typed Telegram IDs:** last, the bot sends a six-digit code to whoever messages it
+    privately, and the code entered on the setup page names the first owner; that owner's
+    `/bind` in a group names the common channel. Messages the bot held from before are dropped, a
+    bot another program already reads is refused, and no `/bind` within 15 minutes stops setup
+    with the way to continue.
+  - **One part again:** `mama init --section <part>` asks one part of a finished setup again
+    (`telegram`, `model`, `timezone`, `connectors`, `discord`, `slack`, `jev`) while MAMA is
+    stopped. The answers get init's checks, the result must pass the checks MAMA runs at boot
+    (delivery routes included) before anything is written, tokens go only to `auth.env`, and the
+    other parts stay as they were. A new bot must already be in the common group.
+  - **Without a terminal:** `mama init --non-interactive` reads `MAMA_INIT_*` variables, and takes
+    the bot token and the pairing code on its setup page.
+  - **No longer offered:** the Kagemusha bridge, which a fresh install cannot use, and the
+    launch-agent question, since the service is installed for you.
+- `/stop` in Telegram stops the turn running in that conversation and keeps the conversation: the
+  message it was answering is told it was interrupted and is not run again, and messages sent
+  after it still run. In the common group an owner stops the common session's turn and a member
+  their own.
+- A daily release check. Once a day the daemon asks npm for the latest MAMA OS release and keeps
+  the answer. `mama status` and `mama doctor` show it without a network call of their own: a newer
+  release and how this install updates (`mama update`, or the git commands for a checkout), that
+  this version is current, or when the last check failed (#534).
+- `mama update` updates an npm install to the latest release, or to the version you name:
+  - **Nothing changes first:** it asks the registry npm uses and shows the plan (`--dry-run`
+    stops there). It installs the new version next to the old one, so a failed download changes
+    nothing. A version older than the running one is refused (#535), and so is a release whose
+    Node.js range (`engines`) leaves out the Node that MAMA runs on (#539).
+  - **Then the swap:** it lets running turns finish as `mama stop` does, stops MAMA, takes a
+    backup with credentials and swaps the two versions. The new version writes `start.sh` and the
+    service file, checks the install, and starts with new work held. Once it runs and its viewer
+    answers, the held work runs, and the backup and the old version are removed (#535).
+  - **A failed step puts the old version back** with its own `start.sh` and service file, and
+    starts it. A check that newly fails under the new version counts as a failed step. The
+    database comes back from the backup only when the new version changed its schema, and the
+    report says how many inputs that arrived after the backup were dropped (#535).
+  - **Cut off:** if `mama update` itself is killed, `mama doctor`, and `mama status` on a stopped
+    install, name the `mama update --rollback` command that resolves it. `mama restore` refuses
+    until then (#535).
+  - **A git checkout** gets the commands that update it instead: stop, `git pull`,
+    `pnpm install`, `pnpm build`, `service install` and `service start` (#535).
+  - **The first update** needs a `start.sh` that this version's `mama service install` wrote, and
+    says so otherwise (#535).
+  - On an install the install command made, the report ends by naming the install command when
+    the new release pins another Node.js (#539).
+- `/update` in Telegram updates MAMA. Only an owner can run it, in their own DM or in the common
+  group. It runs `mama update` as a job of its own, with no model turn, so it works even when the
+  backend does not. Progress comes back to the same chat: versions, steps and error codes, never a
+  path. While an update runs, another `/update` says only since when. A git checkout answers with
+  the commands that update it; asked in the group, those go to the owner's DM, since they name
+  folders on MAMA's machine. `/update` is in the bot's command menu (#536).
+- An install command, `install.sh`, attached to each MAMA OS release starting with this one
+  (#538):
+  - It runs on macOS and Linux, on x64 or arm64, and reads no terminal. A new install is given
+    its backend (Claude Code or Codex) with `--backend`, and `--non-interactive` or `--no-init`.
+  - It puts Node.js in `~/.mama/node`, at a version it pins and checks by hash, MAMA OS in
+    `~/.mama/npm`, and a `mama` command in `~/.mama/bin`. The backend is installed with its
+    vendor's installer when none that runs is on PATH.
+  - It adds `~/.mama/bin` to PATH in a marked block of your shell's startup file (for fish it
+    prints the line instead), then runs `mama init --non-interactive`.
+  - On Linux it shows one `sudo` command and runs it: MAMA's folders under `/var/lib/mama`, and
+    linger, so the service keeps running after you log out. If sudo is refused, it prints the
+    command and goes on.
+  - Run again, it skips what is already in place. It will not take over a MAMA home that another
+    install set up.
+  - When a release pins another Node.js, running it again moves MAMA to that Node with
+    `mama update --node` (#539). That lets running turns finish, stops MAMA, swaps the Node in and
+    checks that MAMA starts on it. A new major version first rebuilds the installed packages for
+    that Node, before anything stops. If a step fails, the old Node is put back and started. If
+    the move is cut off, the next run of the install command finishes or undoes it, and
+    `mama status` and `mama doctor` say so.
+  - `mama doctor` warns when such an install runs another Node.js than its release pins (#539).
+- How to get `gws` when a Google source needs it (Calendar, Gmail, Drive, Sheets). `mama init`,
+  `mama init --section connectors` and `mama doctor` look for it where MAMA's service runs it: on
+  start.sh's PATH, or, before `mama init` has written start.sh, on the PATH it will write, which
+  carries the folder where the terminal finds `gws`. When the service would not find it, they
+  print how to install it and how to sign in. On an install the install command made, both
+  commands use MAMA's own Node and put `gws` where the service finds it:
+  `PATH="$HOME/.mama/node/bin:$PATH" ~/.mama/node/bin/npm install -g --prefix ~/.mama/npm @googleworkspace/cli`,
+  then `PATH="$HOME/.mama/node/bin:$PATH" ~/.mama/npm/bin/gws auth login --scopes <scopes>`.
+  Other installs get `npm install -g @googleworkspace/cli` or `brew install googleworkspace-cli`,
+  then `gws auth login --scopes <scopes>`. The login names the OAuth scope of every Google source
+  that is on (see Changed), since one login serves them all. Before it, `mama init` and
+  `--section` name the OAuth client gws signs in through: a Desktop app client from Google Cloud
+  Console, saved as `~/.config/gws/client_secret.json`. When only the terminal finds `gws`, they
+  say that `mama service install` adds its folder. MAMA's service does not start while such a
+  source is on and `gws` is missing, and they say so: `mama init`, continuing a setup that
+  stopped, names `gws` again and says to install it now and run the install command again, and
+  `--section` no longer enables the source (below). Doctor's fix for a source that does not
+  start, or whose sign-in is refused, names the same login command, and the sources' own errors
+  point to `mama doctor` for those commands instead of a bare `gws auth login` (#543).
+- `mama init --section connectors --non-interactive` enables sources without a terminal, for the
+  person's agent, while MAMA is stopped:
+  - It reads `MAMA_INIT_CONNECTORS`, a JSON object of `connectors.json` blocks keyed by source
+    name, checked as boot checks `connectors.json`. A source name or setting MAMA does not read is
+    refused.
+  - The tokens the sources read, as each source names them (Trello's key too), are entered on the
+    setup page, one field each, and go only to `auth.env`.
+  - The other parts of `mama init --section` still need a terminal.
+- A source is enabled only once its tool is installed where MAMA's service finds it and signed
+  in, from either form of `mama init --section connectors`. With a Google source and `gws`
+  missing from start.sh's PATH, boot stopped; signed out, every poll failed. The section saves
+  nothing and prints how to install `gws`, or the OAuth client file and the login
+  (`gws auth login --scopes <scopes>`, naming the OAuth scope of every Google source that is on,
+  since one login serves them all), then "Then run this again." The sign-in is each source's own check, run in the
+  environment start.sh gives the daemon: one read with that source's own scope (Gmail its
+  profile, Drive `about`, Sheets its first spreadsheet, Calendar the calendar), so a sign-in made
+  for other services is refused too, with gws's reason.
+- Each refusal of `mama init --section`, an expired setup page included, ends by saying MAMA is
+  still stopped and how to start it (`mama service install` first while no service is
+  installed). On an install the install command made, the section's lines
+  name `~/.mama/bin/mama`.
+- An enabled source already in `connectors.json` that boot cannot build refuses the section, which
+  names it and says how to turn it off: its block with `"enabled": false` in
+  `MAMA_INIT_CONNECTORS`.
+- `mama init --non-interactive` opens a setup page on this machine for the bot token and the
+  pairing code, once every other answer has been checked:
+  - The page listens on 127.0.0.1 at a path of 32 random bytes, and answers only a request whose
+    one Host header names `localhost`, `127.0.0.1` or `[::1]`, on any port. The address goes
+    only into `open.html`, a 0600 file in a 0700 folder, which init opens with `open` or `xdg-open`;
+    the address is never printed or passed as an argument, and the folder goes with the page. If
+    no browser opens, init prints the file's `file://` path.
+  - It takes the token, checked with Telegram, then the code the bot sent, by form POST. A refused
+    token or a wrong code is shown with its form again. After one token and one code it closes.
+  - Unused, it closes after 15 minutes, and setup stops without writing the setup; only the two
+    folders it made before the page opened stay. Neither the token nor the address appears in a
+    printed line or on the page.
+
+### Changed
+
+- The Google login MAMA prints (setup, `init --section connectors`, `mama doctor`) asks for
+  explicit scopes, `gws auth login --scopes <scopes>`: read-only for Gmail, Calendar and Sheets,
+  and full Drive access, which `deliver.drive.file` needs to upload into the owner's folder and
+  set its readers. It was `-s <services>`, which in a terminal opened gws's scope picker and
+  otherwise asked for gws's defaults (`gmail.modify`, full Calendar and Sheets). An existing
+  sign-in keeps working; signing in again with the printed line narrows it.
+- A closing summary, once checked, is not ordered again even if a later write clears or replaces
+  it. Before, an order was placed again when that happened within a week.
+- `mama stop` lets running work finish first. MAMA claims nothing new: messages, source changes
+  and reports that arrive wait for the next start, and Telegram commands such as `/stop` still
+  answer. The stop waits until running turns finish and their replies are delivered, and prints
+  what it waits for. It gives up after one `agent.max_turn_ms` for each turn that may still run,
+  plus a minute, or when the daemon stops answering; then nothing changes and it exits 1.
+  `mama stop --now` stops at once, as before. `mama service stop`, `mama service restart`,
+  `mama uninstall` and, on macOS, `mama service uninstall` stop the same way, and `mama status`
+  shows while a stop holds new work. A daemon older than this version refuses to drain, and
+  `mama stop` then names `--now` (#533).
+- `mama backup --restart` stops a running install the same way, backs it up and starts it again
+  through its service, also when the backup fails. Without an installed service it refuses before
+  it stops anything (#533).
+- `mama status` shows the Node.js version the daemon runs (#539).
+- `mama uninstall --data` also removes the program the install command put in the MAMA home
+  (Node.js, MAMA OS and the `mama` command), after everything else. Without `--data` it names that
+  program as staying. Both name the startup files that hold the install command's PATH block, for
+  you to remove. `mama backup` no longer lists that program as left out, since the install command
+  makes it again (#539).
+- `mama service install`, for an npm install, also puts the npm prefix's `bin` folder on
+  `start.sh`'s PATH, where npm puts commands installed beside MAMA (#539).
+- The install script asks nothing and runs from an agent's shell. A found backend must run before
+  the installer is skipped: its `--version` must exit 0 and print a version, so a shim with no
+  backend behind it gets the vendor's installer. A set-up install needs no flags: it runs
+  `mama init --non-interactive`, and without `--backend` it keeps the backend it has.
+- Slack, Chatwork and Trello sources read only `MAMA_SLACK_TOKEN`, `MAMA_CHATWORK_TOKEN` and
+  `MAMA_TRELLO_TOKEN`, so the setup page never takes another secret, such as the owner bot's
+  token or `MAMA_AUTH_TOKEN`. A block without `auth.tokenName` reads that name. A Slack or
+  Chatwork block without one read `SLACK_BOT_TOKEN` or `CHATWORK_API_TOKEN` before; it now needs
+  `MAMA_SLACK_TOKEN` or `MAMA_CHATWORK_TOKEN` in `auth.env`, and doctor names the one missing. A
+  block that names any other variable stops boot until it is corrected, and doctor names it.
+- `mama doctor`'s fix for a source token that is missing or refused names
+  `mama init --section connectors --non-interactive` with that source's block, whose setup page
+  takes the token, instead of `mama secret set`, which needs a terminal. A messenger's token
+  still names `mama secret set`.
+- The package README and the install guide (`docs/start/owner-setup.md`) describe setup through
+  the person's agent: the sentence to give it, naming this repository, and the install command it
+  runs, with `npm install -g` for a person who keeps their own Node.js. The guide lists the
+  supported versions of Node.js, Claude Code, Codex and macOS with their sources, what the install
+  command makes, how a new Node.js release is moved to, and the known limits: no setup path yet for
+  Linux over SSH or without a desktop, and the document tools on a Mac account without its own
+  Homebrew.
+
+### Removed
+
+- The interactive whole setup: bare `mama init` is now a usage error. `mama init --non-interactive`
+  is the setup, run by the person's agent ("Set up through your agent" in
+  `docs/start/owner-setup.md`), and its messages say to run the install command again. The tunnel
+  settings are read from the environment: `MAMA_CF_ACCESS_ISSUER`, `MAMA_CF_ACCESS_AUD` and
+  `MAMA_VIEWER_HOSTNAMES` together, and optionally `MAMA_VIEWER_OWNER_EMAILS`. Sources, Discord,
+  Slack and Jev are set up with `mama init --section`.
+- The init variables `MAMA_INIT_OWNER_TELEGRAM_ID` and `MAMA_INIT_COMMON_CHAT_ID`, and
+  `MAMA_TELEGRAM_TOKEN` as an init variable (the secret name stays): the setup page takes the token,
+  and the bot's pairing code and `/bind` name the owner and the common group.
+- The package no longer installs Express. Its only use was an old report router with write routes
+  that nothing ever served.
+
+### Fixed
+
+- A Notion, Discord or Telegram source whose block names another token than its own is refused
+  when the source is built, in the section, doctor and boot; before, only its start in boot
+  refused it.
+- Gmail, Drive and Sheets' sign-in check is a read with the source's own scope. It ran
+  `gws auth status`, which exits 0 signed in or not and does not say which services a sign-in
+  grants, so doctor reported a signed-out source, or one without its scope, as signed in.
+- Calendar starts as the other Google sources do, when `gws` runs. Its calendar read is its sign-in
+  check, so a sign-in that ended (a testing-mode client's, after 7 days) fails its polls and
+  doctor's check instead of stopping MAMA at boot.
+- A backend failure such as a signed-out Claude CLI or an API error no longer arrives as MAMA's
+  answer. The turn fails, its message is told it was interrupted, and `daemon.log` names the
+  error. Before, the CLI's error text was sent as the reply and the run was recorded as committed
+  (mama-core).
+- A scheduled full report or reminder that a newer report already covered is no longer sent.
+  Before, a report whose first send failed stayed queued and kept being retried, so it could still
+  go out days late; one had waited 13 days. Reports already stuck this way close after the next
+  full report is sent (#542).
+- After a report's send fails, MAMA no longer writes the same hour's report again every minute
+  (#542).
+- If the clock is behind the latest report sent, MAMA queues no report and logs an error each
+  minute naming that report's time, until the clock passes it (#542).
+- `mama stop` no longer refuses a MAMA that is just starting. In its first moments MAMA holds the
+  install before it can answer the stop or say which process it is. The stop used to report
+  "does not answer on its control socket" and leave it running, or report "unknown (pid 0) holds
+  the install" as still running after it had already stopped it (macOS). It now waits up to 5
+  seconds for MAMA to answer, then lets it finish what runs and stops it as usual. `mama stop
+--now` waits the same way, only while the holder is still unnamed, before it stops the service.
+  Running the install command again right after a Node move was cut off hit this: the install
+  command stopped with "MAMA on it did not stop" and changed nothing (#546).
+
+### Security
+
+- gws's credential store is now closed to the agents' own file reads and shell, as MAMA's own
+  credentials are (owner, 2026-10-31): its config directory (`~/.config/gws`, the legacy
+  `~/Library/Application Support/gws`, or the one `GOOGLE_WORKSPACE_CLI_CONFIG_DIR` names) and a
+  `GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE`. MAMA's Google sources and `google.read` run on that
+  sign-in, and an agent that could read it, or run `gws auth export` against it, could carry the
+  refresh token, with Drive write access, out in a reply or a fetched URL. Claude's Read rules
+  and shell sandbox and the Codex permission profile all deny it; the daemon's own gws calls are
+  unaffected. Other tools' credential stores stay as they were.
+- Another website open in your browser can no longer read through MAMA's viewer in your name.
+  Before, a link or a page your browser had allowed onto this machine could make one viewer
+  request, such as a memory search with words it chose. MAMA ran that search as yours and kept
+  the words in its record of your actions. The viewer now answers such a request with 403 and runs
+  nothing. It records the request in `security-events.jsonl` as `cross_origin` and alerts you as
+  for other viewer security events. A page on another port of this machine counts as another
+  website. The viewer itself, a link or bookmark that opens it, curl and local tools work as
+  before. Through the tunnel, a bookmark to an `/api` address opened after your Cloudflare Access
+  sign-in expired comes back from the sign-in page as another website's request and gets 403;
+  open the viewer instead.
+- The board's live updates allow 8 open connections at once. Another connection is refused with
+  503 and a line in `daemon.log`, instead of each one adding memory without limit. The browser
+  does not retry a refused connection: that board keeps its content and its refresh button but
+  shows no live updates until the page is reloaded. A connection whose browser left while MAMA
+  was still checking its Cloudflare Access sign-in is no longer kept open for good.
+
+## [0.78.0] - 2026-10-16
+
+### Fixed
+
+- A generated `start.sh` keeps the package manager's tool folders on PATH (`/opt/homebrew/bin`,
+  `/usr/local/bin`), when they exist, ahead of the system's. The agent's shell runs
+  the tools the owner installed there, such as python3 with its packages; they had been dropped.
+
+- `member_root` and `tools_root` are compared by their real letter case, so on a case-insensitive
+  disk a root written as HOME in another case (`/USERS/name`) is refused as overlapping HOME,
+  instead of being accepted and placing member workspaces inside the owner's home.
+
+### Added
+
+- `mama uninstall [--dry-run] [--data [--toolkit]]` stops whatever holds the install and removes
+  the service. With `--data`, once the MAMA home's path is typed back on a terminal, it also removes
+  the MAMA home, each registered person's folder under `member_root` and the retired ones, and the
+  common skills under `tools_root` (`--toolkit`: the toolkit's versions too); `member_root` and
+  `tools_root` go only once empty, so a misconfigured root loses nothing but MAMA's entries. Paths
+  the config sets outside the MAMA home are listed as staying. `--dry-run` lists it all.
+
+- The daemon writes its own output to `daemon.log` (`logging.file`), rotated at 10 MB with five
+  compressed archives; `security-events.jsonl` rotates at 5 MB the same way. The service manager
+  keeps only what comes before the daemon reads its config, in `logs/crash.log`, which `start.sh`
+  empties at start past 1 MB (`mama service install` rewrites the launch files). Writes stay
+  synchronous, so no line is lost or reordered across a rotation, and the file is emptied in place,
+  never replaced, so a launch file that still redirects into it keeps working. A rotation that
+  fails is written to the log and tried again after another limit's worth.
+- `mama logs [-n <lines>] [--follow]` prints the daemon log's last lines and follows it across a
+  rotation.
+
+- MAMA OS refuses to open a database a newer version migrated, before anything writes to it, and
+  the daemon stops with a clean exit so its service does not restart into the refusal; other
+  commands print the refusal's own text. `mama doctor` checks the schema read-only against what this version knows, per migration source:
+  a newer one fails (install the version that wrote it, or restore a backup taken with this one),
+  an older one reports that the next start migrates it, and an unreadable file is reported.
+
+- `mama restore <archive>` puts a `mama backup` archive onto a stopped install. The manifest is
+  read as untrusted: only the names a backup keeps, nothing beneath a link, credentials only in a
+  backup that says it holds them. Files are extracted and checked against their hashes, links
+  are made from the manifest (absolute ones too), and modes are set as recorded. The restored
+  config keeps the backup's settings with this install's paths, and each part goes where that
+  config puts it, folder by folder. Attachment paths in mailbox inputs and the connector event
+  index move to this install's roots in one pass, with the tables' update triggers set aside so
+  no event is renumbered and delivered again; raw stores and evidence keep theirs. Each
+  destination goes aside while its copy takes its name, under a write-ahead journal: a failure
+  puts everything back, and after an interruption the daemon and `mama doctor` refuse until
+  `mama restore --rollback` resolves it. The target keeps its credentials when the archive has
+  none, and its `start.sh`; the owner's Codex threads start over. While a restore is unfinished
+  the daemon, `register-owner` and `mama backup` refuse with a clean exit, so a service does not
+  restart into it.
+- `mama backup` archives the wiki on its own wherever it is, so a restore puts it where that
+  install keeps its wiki.
+
+- `mama backup [--include-secrets] [--logs]` writes one archive of a stopped install to
+  `~/.mama/backups/` (0600), the one folder the agents cannot read: the database copied with
+  SQLite's backup and checked with `integrity_check`, the raw stores checked too, the MAMA home's
+  state, the workspace, every person's folder under `member_root`, the published common skills,
+  the wiki MAMA writes and Jev's vocabulary, each where config puts it. A manifest records each
+  entry's mode, symlink target and SHA-256 and every configured path as written and as it really
+  is, and the archive is read back against it before it is kept. Credentials (auth.env, the Codex
+  login, the Jev key, an MCP configuration with servers besides MAMA's, and a config or start.sh
+  that holds a token) go in only with `--include-secrets`, logs only with `--logs`; Codex homes
+  and their sessions never (sessions start over after a restore). It names everything it left out,
+  and it is refused beside a running daemon and for a kept file or folder that is a link.
+
+- `mama doctor` checks an install as its service would run it, without changing it: config and
+  `connectors.json` as boot loads them, `member_root`, the Node in `start.sh` (present, outside one
+  version's folder, and able to load MAMA's SQLite module), the backend on that script's `PATH`
+  with the daemon's environment (its version against the oldest one MAMA was verified on, Claude
+  Code 2.1.299 and Codex 0.160.1, and whether it is signed in), the shell sandbox (it starts one),
+  the secrets each enabled messenger and source needs and each source started as boot starts it and
+  asked whether its credentials work, the Telegram token and whether the bot is in the common group
+  and reads it, the toolkit, the daemon (answering, booted, each source's last poll) or the port it
+  would bind, the service manager and each log past its cap. Each problem names what to do, and it exits
+  1 when a check fails. `--json` for scripts, `--offline` makes no network call (Telegram and the
+  sources are not asked), and `--report` prints a summary for a bug report: versions, platform,
+  setting and source names, the checks in doctor's own words, the last boot's stages and recent
+  errors reduced to failed stages, connector names and error codes. Paths, values, ids and message
+  text never enter it.
+
+### Changed
+
+- The agents can no longer read `~/.mama/backups/`, which can hold every MAMA credential.
+- Poll state is written to a temporary file and renamed into place; an unreadable one is kept as
+  `poll-state.json.corrupt-<time>-<pid>` with an error in the log, where it used to be dropped
+  without a word.
+
+- A daemon that fails to boot prints the stage that failed and points to `mama doctor`.
+- The Chatwork and Slack sources name the token they read (`auth.tokenName`) when asked what they
+  need; they named the default.
+- The iMessage source opens `chat.db` read-only and only when it exists; a missing database used
+  to be created empty.
+- `init` and `service install` write Homebrew's stable `opt/node` path into `start.sh` instead of
+  the versioned Cellar path that an upgrade removes. `service install` reads `$HOME`, `${HOME}` and
+  `~` in the old `PATH` as the home folder, so it no longer reports them as dropped.
+
+- The daily page closes the day: the daily turn fixes what it got wrong (a revision with its
+  evidence for a wrong or stale item, a saved or revised lesson), saves an owner correction that
+  was only promised as a lesson (a standing rule is listed for the owner to confirm in the common
+  channel), settles up to ten items in progress or review whose latest source event is over 30
+  days old, and checks the previous day's lessons against what it can read. It had listed its
+  misses on the page only, and the next day repeated one.
+- `work.list` takes `lastEventBefore`: items whose latest source event is before a time, for stale
+  work that a backfill or correction rewrote later (`changedBefore` compares write time).
+- One process holds an install at a time. The daemon, a replay or backfill, and `register-owner`
+  take an exclusive lock on `~/.mama/runtime/daemon.lock` before they open the database, so a
+  second one is refused before it changes anything (a second daemon used to migrate the live
+  database, rewrite the workspace settings and reset the web fetch mode before failing). The
+  operating system releases the lock when the process ends; a failed stop keeps it until then. A
+  refused daemon exits cleanly.
+- `mama status` asks the running daemon through `~/.mama/daemon.sock` and shows its version,
+  boot stage, running turns, waiting inputs, connectors and last error (`--json` for scripts); it
+  exits 0 when running and 3 when stopped, and it works on Linux, where it used to fail because it
+  called `launchctl`. `mama stop` unloads the LaunchAgent that runs the daemon or asks the daemon to stop, waits up to
+  two minutes until the install is released, and says when something else holds it or started in
+  its place.
+- A stop during boot unwinds what has started; signals were handled only after boot.
+- `mama service install|start|stop|restart|status|uninstall` writes and runs the service: a
+  LaunchAgent on macOS, a systemd user unit on Linux (`--enable-linger` keeps it running after
+  logout). Both restart the daemon only after a failure, so a stop or a refused second daemon stays
+  stopped; the LaunchAgent used to restart on every exit. The unit signals the daemon alone
+  (`KillMode=mixed`), so it stops its children in order. `install` regenerates `start.sh`, carries
+  its `export` lines over verbatim, names what else it does not reproduce and every change to what
+  the daemon runs (exec target, PATH, log level), keeps the replaced files under `runtime/`, and
+  refuses to replace a `start.sh` that mama did not write without `--replace`, or to write one when
+  the backend cannot be found. `start` starts a loaded LaunchAgent whose daemon has exited; on
+  Linux `mama stop` and `mama status` go through the unit.
+- A daemon stopped by a signal exits 128 plus the signal's number (143 for SIGTERM), as a killed
+  process would, so its service brings it back; a stop asked for through `mama stop` exits 0.
+- The generated `start.sh` exports `MAMA_LOG_LEVEL` from `config.yaml`'s `logging.level`. The core
+  logger reads only that variable, so a fresh install logged at `ERROR` whatever the config said.
+
 ## [0.77.0] - 2026-10-15
 
 ### Upgrading

package/README.md

@@ -1,54 +1,82 @@
 # MAMA OS
 
-One owner agent on Claude or Codex watches connected work, keeps task revisions and evidence,
-answers on Telegram, publishes reports and a board, and recalls corrections.
+A common session, a DM session per registered person and a group session per member, on Claude or
+Codex, watch connected work, keep task revisions and evidence, answer in Telegram (each person's DM
+and the common group), Discord or Slack, publish reports and a board, and recall corrections.
 [mama-core](../mama-core/README.md) supplies the shared engine.
 
-Current manifest: **0.77.0**. Install with `npm install -g @jungjaehoon/mama-os` (Node.js 22.13+)
-and follow [owner setup](../../docs/start/owner-setup.md).
+Current manifest: **0.79.0**. Install it through your agent: on the Mac that will run MAMA, tell
+Claude Code or Codex "Install MAMA OS from https://github.com/jungjaehoon-lifegamez/MAMA by
+following its owner setup guide, docs/start/owner-setup.md". See
+[owner setup](../../docs/start/owner-setup.md), with the supported versions.
 
 ## Start and operate
 
+The agent runs the install command. It installs MAMA's own Node.js, MAMA OS and, when needed, the
+backend, then sets MAMA up and starts it:
+
+```bash
+curl -fsSL https://github.com/jungjaehoon-lifegamez/MAMA/releases/latest/download/install.sh | MAMA_INIT_MODEL=<model> sh -s -- --backend <claude|codex> --non-interactive
+```
+
+With your own Node.js 22.13 or newer, install with npm instead, then run setup:
+
 ```bash
 npm install -g @jungjaehoon/mama-os
-mama init
+MAMA_INIT_BACKEND=<claude|codex> MAMA_INIT_MODEL=<model> mama init --non-interactive
 ```
 
 From a checkout, run `pnpm install` and `pnpm build`, then use
-`node packages/standalone/dist/cli/index.js` in place of `mama`. Onboarding is terminal-only: the owner types tokens
-with echo off. It writes configuration and optional launchd files; backend login and service
-startup are separate steps.
-
-For Telegram's common session, create a group with the bot, even for a solo owner, and enter
-its negative group or supergroup ID in `mama init`. Private chats always enter personal sessions.
-Before starting the daemon, set `member_root` outside HOME in `config.yaml` and run
-`mama register-owner <telegram id>` for each owner's positive user ID.
-
-| Command                                       | Purpose                                          |
-| --------------------------------------------- | ------------------------------------------------ |
-| `mama init`                                   | Set up the owner, backend and connectors         |
-| `mama secret set <NAME>` / `mama secret list` | Rotate a token / list names only                 |
-| `mama daemon`                                 | Run the configured daemon in the foreground      |
-| `mama replay`                                 | Replay prepared historical inputs in day windows |
-| `mama status` / `mama stop`                   | Report running/stopped / stop the process        |
+`node packages/standalone/dist/cli/index.js` in place of `mama`. Setup reads its answers from
+`MAMA_INIT_*` variables and opens a page in the browser on this machine, where the owner enters the
+bot token and the pairing code; nothing secret goes through the chat or a terminal. Sign in to the
+backend first; setup checks it, writes the setup, registers the first owner, installs the document
+toolkit and starts the service.
+
+For Telegram's common session, create a group with the bot, even for a solo owner, and send
+`/bind` there when setup asks. Private chats always enter personal sessions.
+Setup pairs you through a code the bot sends you and registers you as the first owner; `mama register-owner <telegram id>` registers
+another owner while the daemon is stopped.
+
+| Command                                            | Purpose                                              |
+| -------------------------------------------------- | ---------------------------------------------------- |
+| `mama init --non-interactive`                      | Set up and start MAMA, with the first owner          |
+| `mama init --section connectors --non-interactive` | Enable sources, with MAMA stopped; the agent runs it |
+| `mama register-owner <telegram id>`                | Register another owner while MAMA is stopped         |
+| `mama tools install`                               | Install or update the document toolkit               |
+| `mama secret set <NAME>` / `mama secret list`      | Rotate a token / list names only                     |
+| `mama daemon`                                      | Run the configured daemon in the foreground          |
+| `mama backfill <file>`                             | Write a prepared past-period backfill file           |
+| `mama replay`                                      | Replay prepared historical inputs in day windows     |
+| `mama status` / `mama stop`                        | Report running/stopped / stop the process            |
 
 See [CLI flags](../../docs/reference/cli.md) and
 [launchd management](../../docs/guides/troubleshooting.md).
 
 ## Current surface
 
-- **Owner chat:** Telegram, Discord or Slack, each with an allowed chat and owner sender
-  ([messengers](../../docs/guides/messengers.md)).
-- **Five source connectors:** Chatwork, Slack, Trello, Kagemusha (read-only local bridge),
-  and Google Calendar through `gws`.
+- **Messengers:** in Telegram, a DM per registered person and the common group; Discord and
+  Slack keep one owner channel ([messengers](../../docs/guides/messengers.md)).
+- **People:** each person's DM session has its own records, scheduled jobs, notices and skills;
+  an owner's DM also reads the common records. Members without the owner role work in the group
+  in a session of their own ([people and DMs](../../docs/guides/people.md)).
+- **Sources:** Chatwork, Slack, Discord, Telegram groups, Trello, Notion, Google Calendar, Gmail,
+  Drive and Sheets through `gws`, iCal feeds, Obsidian, iMessage, Claude Code and a read-only
+  Kagemusha bridge ([sources](../../docs/guides/connectors.md)).
 - **Records:** tasks and revision history, a four-slot board, wiki pages, daily journals,
-  lessons, preferences and constraints.
+  lessons, preferences, constraints, workflows and skills.
+- **Documents:** a managed toolkit (`mama tools install`) with python-pptx, python-docx, openpyxl,
+  PyMuPDF, numpy, pandas, matplotlib, LibreOffice and Noto CJK fonts; on macOS `document.render`
+  turns a workspace file into a PDF and page images.
+- **Web:** for owners, turns where a person speaks search the web and, on Claude, open pages;
+  turns with no person in them search the web but open pages only from the hosts in
+  `agent.autonomous_web_fetch`. Members without the owner role have no web tools.
 - **Reports:** live deltas, full reports at 08/13/18 and hourly reminders at 09–21, in the
   configured time zone.
 - **Viewer:** board, work, memory graph, wiki, logs and security events; read-only data routes.
 - **Files:** source attachment lookup/download, native workspace processing,
-  `deliver.<messenger>.file` to the owner's chat and `deliver.drive.file` for files over the
-  messengers' limit.
+  `deliver.<messenger>.file` to the caller's chat and `deliver.drive.file` for files over the
+  messengers' limit; an owner's DM fetches Drive files with `drive.download`.
 
 Assembly lives in `src/runtime/` and `src/cli/commands/daemon.ts`; actions in `src/api/`,
 collectors in `src/connectors/`, Telegram in `src/gateways/`, replay in `src/replay/`,
@@ -57,8 +85,8 @@ and viewer sources/assets in `ui/` and `public/viewer/`.
 ## Data, security and status
 
 OS state lives in `~/.mama/`; its database defaults to `~/.mama/memory.db`.
-`config.yaml` and `connectors.json` hold settings; terminal-entered credentials live in
-`auth.env` (0600). Both backends have workspace-only writes and credential-read exclusions.
+`config.yaml` and `connectors.json` hold settings; credentials, entered on the setup page or at a
+terminal, live in `auth.env` (0600). Both backends have workspace-only writes and credential-read exclusions.
 The viewer binds to `127.0.0.1:3847` by default; remote data access requires a bearer token
 or verified Access JWT. See [security](../../docs/guides/security.md).
 
@@ -70,6 +98,7 @@ The [public MCP server](../mcp-server/README.md) and
 [Replay](../../docs/guides/replay.md) · [Viewer](../../docs/guides/viewer.md).
 
 Completion is measured by [INTENT.md](../../INTENT.md); open live checks are in
+[the work plan](../../docs/development/plan.md) and results in
 [checks.md](../../docs/development/checks.md). Run `pnpm test` inside this package, with isolated
 state as described in [testing](../../docs/development/testing.md).
 

package/db/migrations/002-model-runs-parent-index.sql

@@ -0,0 +1,11 @@
+-- A run's child runs are read by parent, and only the product reads them that way: the upkeep and
+-- record-order runners wait for an order run's children, and the write-back scan reads and checks
+-- each question turn with its children. Core never queries by parent, so the index lives with the
+-- package that does. Without it every lookup scans model_runs; on a copy of a live install the
+-- write-back scan took about 3 s per pass, and about 50 ms with this index.
+CREATE INDEX IF NOT EXISTS idx_model_runs_parent
+  ON model_runs(parent_model_run_id)
+  WHERE parent_model_run_id IS NOT NULL;
+
+INSERT OR IGNORE INTO schema_version (source, version, description)
+VALUES ('standalone', 2, 'Index model runs by parent run, for the product runners that read children');

package/db/migrations/003-upkeep-settled.sql

@@ -0,0 +1,15 @@
+-- Upkeep subjects the runner has settled for good: checked, or lost after its last attempt.
+-- Attempts are counted from the stored order rows, and the mailbox deletes acked rows after seven
+-- days, so without this record a subject whose scan has no time bound (the board reconcile's stale
+-- items) would be ordered three more times every week, kept or lost. A settled subject is never
+-- ordered again; new work on the same thing is a new subject with a new key.
+CREATE TABLE IF NOT EXISTS upkeep_settled (
+  kind TEXT NOT NULL,
+  subject_key TEXT NOT NULL,
+  state TEXT NOT NULL CHECK (state IN ('checked', 'lost')),
+  settled_at INTEGER NOT NULL,
+  PRIMARY KEY (kind, subject_key)
+);
+
+INSERT OR IGNORE INTO schema_version (source, version, description)
+VALUES ('standalone', 3, 'Upkeep subjects settled for good, kept past the mailbox retention');