health-export-mcp 1.7.3 → 1.8.0

package/AGENTS.md

@@ -17,15 +17,19 @@ After configuring, restart the client and ask: **"Use health-export: what's my H
 
 ## Claude Code
 
-One command, no clone:
+One command, no clone, no environment variable on a Mac (1.7.3 finds the app's iCloud Drive folder itself):
 
 ```bash
-claude mcp add --transport stdio health-export \
-  --env "HEALTH_DATA_DIR=$HOME/Library/Mobile Documents/iCloud~ai~healthexport~app/Documents" \
-  -- npx -y health-export-mcp
+claude mcp add health-export -- npx -y health-export-mcp
 ```
 
-Keep the double quotes (the folder name contains a space). Add `--scope user` to use it in every project. No export yet: `claude mcp add --transport stdio health-export-demo -- npx -y health-export-mcp --demo` serves synthetic data.
+Windows, Linux, or an export outside iCloud Drive:
+
+```bash
+claude mcp add health-export --env "HEALTH_DATA_DIR=/path/to/folder" -- npx -y health-export-mcp
+```
+
+Keep the double quotes if the path has a space. Add `--scope user` to use it in every project. No export yet: `claude mcp add health-export-demo -- npx -y health-export-mcp --demo` serves synthetic data. If Agent pairing is on, do not pass `PAIRING_SECRET` on the command line (shell history, `ps`); add it to the entry's `env` in the config file.
 
 ## Claude Desktop
 
@@ -56,7 +60,7 @@ Run `node gen-deeplinks.mjs` and open the generated VS Code link, or add the ser
 
 ## opencode
 
-`opencode.json` (project root) or `~/.config/opencode/opencode.json`:
+`opencode.json` (project root) or `~/.config/opencode/opencode.json`. Drop the `environment` line on a Mac using iCloud Drive; for a pinned checkout use `["node", "/ABSOLUTE/PATH/TO/server.mjs"]`:
 
 ```json
 {
@@ -64,9 +68,9 @@ Run `node gen-deeplinks.mjs` and open the generated VS Code link, or add the ser
   "mcp": {
     "health-export": {
       "type": "local",
-      "command": ["node", "/ABSOLUTE/PATH/TO/health-export-mcp/server.mjs"],
+      "command": ["npx", "-y", "health-export-mcp"],
       "enabled": true,
-      "environment": { "HEALTH_DATA_DIR": "~/Library/Mobile Documents/iCloud~ai~healthexport~app/Documents" }
+      "environment": { "HEALTH_DATA_DIR": "/path/to/folder" }
     }
   }
 }
@@ -74,15 +78,15 @@ Run `node gen-deeplinks.mjs` and open the generated VS Code link, or add the ser
 
 ## OpenClaw
 
-Add the `health-export` block (same shape as Claude Desktop's `mcpServers` entry) to your OpenClaw MCP servers config, then reload.
+Add the `health-export` block (same shape as Claude Desktop's `mcpServers` entry: command `npx`, args `["-y", "health-export-mcp"]`, plus `HEALTH_DATA_DIR` off a Mac) to your OpenClaw MCP servers config, then reload.
 
 ## Hermes
 
-Add the `health-export` block to your Hermes agent's MCP servers config, then restart the daemon.
+Add the same `health-export` block to your Hermes agent's MCP servers config, then restart the daemon.
 
 ## Non-MCP clients, ChatGPT · Gemini · Grok · n8n · Home Assistant
 
-These don't speak MCP, so they don't use this server. Instead, the [MetricBridge](https://www.healthexport.dev) app **POSTs your data to a webhook** (or your own endpoint) and your automation/agent reads that JSON. Every delivery is token-authenticated.
+ChatGPT connects only to remote MCP servers (OpenAI's help centre: "Can I connect to a local MCP server? Not directly", checked 2026-10-27), and the others don't run local MCP servers either, so they don't use this one. Instead, the [MetricBridge](https://www.healthexport.dev) app **POSTs your data to a webhook** (or your own endpoint) and your automation/agent reads that JSON. Every delivery is token-authenticated.
 
 ---
 

package/README.md

@@ -1,6 +1,6 @@
 # health-export-mcp
 
-**An MCP server for your own Apple Health data.** 194 metrics, 16 read-only tools and 22 prompts over local stdio, with zero dependencies, no account and no server of ours in the path. Your agent gets JSON with units, date ranges and coverage, and answers from your numbers.
+**An MCP server for your own Apple Health data.** 194 metrics, 18 tools (16 read-only, plus two that log events to their own file) and 22 prompts over local stdio, with zero dependencies, no account and no server of ours in the path. Your agent gets JSON with units, date ranges and coverage, and answers from your numbers.
 
 <p align="center">
   <a href="https://www.npmjs.com/package/health-export-mcp"><img alt="npm" src="https://img.shields.io/npm/v/health-export-mcp?color=cb3837" /></a>
@@ -11,35 +11,34 @@
   <a href="https://glama.ai/mcp/servers/PhilipAD/health-export-mcp"><img alt="Glama score" src="https://glama.ai/mcp/servers/PhilipAD/health-export-mcp/badges/score.svg" /></a>
 </p>
 
-## Try it in 30 seconds (no iPhone, synthetic data)
+Docs and per-client config: **[healthexport.dev/mcp](https://www.healthexport.dev/mcp/)** · agents can run the setup from **[SKILL.md](https://www.healthexport.dev/SKILL.md)** · privacy: the server reads a local file and makes no network requests, so your health data never reaches us or a cloud AI through it.
+
+## Install: one command
 
 ```bash
-claude mcp add --transport stdio health-export-demo -- npx -y health-export-mcp --demo
+claude mcp add health-export -- npx -y health-export-mcp
 ```
 
-Ask *"Use health-export-demo: how did my HRV this week compare with last week?"* The tool call returns this (every demo answer is watermarked):
+On a Mac that is the whole install: since 1.7.3 the server finds the MetricBridge app's iCloud Drive folder by itself. On Windows or Linux, or for an export in another folder, add `--env "HEALTH_DATA_DIR=/path/to/folder"` before the `--`. Needs Node.js 18 or later. **Claude Desktop:** open [`health-export.mcpb`](https://github.com/PhilipAD/health-export-mcp/releases/latest/download/health-export.mcpb) instead (no JSON, no Node on your PATH). Cursor, VS Code, opencode, OpenClaw, Hermes: [AGENTS.md](AGENTS.md).
+
+Then ask *"Use health-export: how did my HRV this week compare with last week?"* The agent calls `get_trends` and gets numbers that carry their own provenance: unit, exact date ranges, whether each window was complete, and how much history the export holds. This is the real output on 1.7.3 (from the built-in `--demo` dataset, which is synthetic so it can be published; a real export answers with the same fields and without the watermark):
 
 ```json
 [SYNTHETIC DEMO DATA] {"metric":"heart_rate_variability","unit":"ms","window":7,"recent":50.859,"prior":51.306,
- "changePercent":-0.871,"direction":"flat","recentRange":{"from":"2026-08-12","to":"2026-08-18"},
- "windowSatisfied":true,"coverage":{"firstDate":"2025-07-15","lastDate":"2026-08-18","days":400}}
+ "change":-0.447,"changePercent":-0.871,"direction":"flat","recentRange":{"from":"2026-08-12","to":"2026-08-18"},
+ "recentDays":7,"priorDays":7,"windowSatisfied":true,"coverage":{"firstDate":"2025-07-15","lastDate":"2026-08-18","days":400}}
 ```
 
-## Use your real data (about 5 minutes, needs an iPhone)
+**No iPhone yet?** `claude mcp add health-export-demo -- npx -y health-export-mcp --demo` serves that watermarked synthetic dataset, so you can try every tool in 30 seconds before installing anything on a phone.
 
-1. **Export.** Install [MetricBridge](https://apps.apple.com/app/apple-store/id6784185201?pt=129083290&ct=githubreadme&mt=8&ppid=2c28f88a-d94f-48f9-8e6a-74a8d89ce66e) on the iPhone, allow Health read access and tap **Export now**. It writes `.health-cache.json` to iCloud Drive (or a folder, or your LAN). The app has a free trial, then one purchase, no subscription. This server is MIT and free.
-2. **Connect.** Claude Code:
-   ```bash
-   claude mcp add --transport stdio health-export -- npx -y health-export-mcp
-   ```
-   On a Mac the server finds the app's iCloud Drive folder by itself (since 1.7.3). Elsewhere, or for another folder, add `--env "HEALTH_DATA_DIR=/path/to/folder"`, with the quotes if the path has a space.
-   **Claude Desktop:** download [`health-export.mcpb`](https://github.com/PhilipAD/health-export-mcp/releases/latest/download/health-export.mcpb) and open it; no JSON and no Node on your PATH needed. Cursor, VS Code, opencode, OpenClaw and Hermes: see [AGENTS.md](AGENTS.md) and the [quickstart](#connect-apple-health-to-your-ai-agent-quickstart).
-3. **Check it arrived.** `npx -y health-export-mcp --doctor` prints the folder it chose and why, each file's age, and freshness. iCloud can take a few minutes to bring a new export to the Mac.
+## Use your real data (about 5 minutes the first time, needs an iPhone)
 
-Then ask *"Use health-export: compare my resting heart rate this month with last month."*
+1. **Export.** Install [MetricBridge](https://apps.apple.com/app/apple-store/id6784185201?pt=129083290&ct=githubreadme&mt=8&ppid=2c28f88a-d94f-48f9-8e6a-74a8d89ce66e) on the iPhone, allow Health read access and tap **Export now**. It writes `.health-cache.json` to iCloud Drive (or a folder, or your LAN). The app has a 7-day free trial, then one purchase ($24.99), no subscription. This server is MIT and free.
+2. **Connect.** The one command above (Claude Code), the `.mcpb` (Claude Desktop), or the block for your client in [AGENTS.md](AGENTS.md).
+3. **Check it arrived.** `npx -y health-export-mcp --doctor` prints the folder it chose and why, each file's age, and freshness. iCloud can take a few minutes to bring a new export to the Mac.
 
 <p align="center">
-  <img src="assets/architecture.svg" alt="Apple Health exports to iCloud, a folder, or your LAN; health-export-mcp reads it and serves 16 query tools to your AI agent" width="100%" />
+  <img src="assets/architecture.svg" alt="Apple Health exports to iCloud, a folder, or your LAN; health-export-mcp reads it and serves 18 tools to your AI agent" width="100%" />
 </p>
 
 ---
@@ -83,12 +82,12 @@ The companion iOS app **[MetricBridge](https://www.healthexport.dev)** exports y
 **Fastest, one command (Claude Code):**
 
 ```bash
-claude mcp add --transport stdio health-export \
-  --env "HEALTH_DATA_DIR=$HOME/Library/Mobile Documents/iCloud~ai~healthexport~app/Documents" \
-  -- npx -y health-export-mcp
+claude mcp add health-export -- npx -y health-export-mcp
+# Windows, Linux, or an export outside iCloud Drive:
+claude mcp add health-export --env "HEALTH_DATA_DIR=/path/to/folder" -- npx -y health-export-mcp
 ```
 
-Everything before `--` is an option for `claude mcp add`, everything after it is the command that starts the server. The path is double-quoted because the iCloud folder name contains a space, and `$HOME` is used because a quoted `~` is not expanded by the shell. Exporting somewhere else? Replace the path with your own folder. Add `--scope user` to make the server available in every project (the default scope is the current project only). Check it with `claude mcp list`.
+Everything before `--` is an option for `claude mcp add`, everything after it is the command that starts the server. On a Mac the server reads the app's iCloud Drive folder when `HEALTH_DATA_DIR` is unset (1.7.3+); if you set it to that folder by hand, double-quote it (the folder name contains a space) and use `$HOME`, because a quoted `~` is not expanded by the shell. Add `--scope user` to make the server available in every project (the default scope is the current project only). Check it with `claude mcp list`.
 
 **Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`), and any client that takes an `mcpServers` block:
 
@@ -97,14 +96,13 @@ Everything before `--` is an option for `claude mcp add`, everything after it is
   "mcpServers": {
     "health-export": {
       "command": "npx",
-      "args": ["-y", "health-export-mcp"],
-      "env": { "HEALTH_DATA_DIR": "~/Library/Mobile Documents/iCloud~ai~healthexport~app/Documents" }
+      "args": ["-y", "health-export-mcp"]
     }
   }
 }
 ```
 
-> `npx -y` fetches the published package at run time without an install prompt (npm verifies package integrity), so it runs anywhere with no clone or absolute path. The server expands a leading `~` in `HEALTH_DATA_DIR` itself, so the JSON form can keep it. Prefer to pin a vetted local checkout instead? Use `"command": "node", "args": ["REPLACE_WITH_ABSOLUTE_PATH/server.mjs"]`, get the path with `node -e "console.log(process.cwd()+'/server.mjs')"` inside the repo.
+> Off a Mac, or for another folder, add `"env": { "HEALTH_DATA_DIR": "/path/to/folder" }` to the entry (a leading `~` is expanded by the server). `npx -y` fetches the published package at run time without an install prompt (npm verifies package integrity), so it runs anywhere with no clone or absolute path. The server expands a leading `~` in `HEALTH_DATA_DIR` itself, so the JSON form can keep it. Prefer to pin a vetted local checkout instead? Use `"command": "node", "args": ["REPLACE_WITH_ABSOLUTE_PATH/server.mjs"]`, get the path with `node -e "console.log(process.cwd()+'/server.mjs')"` inside the repo.
 > Or skip JSON entirely, drag **`health-export.mcpb`** into **Claude Desktop → Settings → Extensions**.
 
 **Auto-configure from a clone:**
@@ -144,25 +142,27 @@ Restart the client and try:
 
 ---
 
-## The 16 MCP tools
+## The 18 MCP tools
 
 Full reference with request/response examples: **[healthexport.dev/mcp](https://www.healthexport.dev/mcp/#tools)**.
 
 | Tool | What it does |
 |---|---|
 | `get_mcp_status` | Health check: source, metric/workout counts, which context files exist, latest data date, and a `freshness` summary. **Call first.** |
-| `get_freshness` | How current the export is: `stale` against a stated threshold (26 h by default, `HEALTH_STALE_AFTER_HOURS`, or `maxAgeHours`), `age_hours`, `as_of`, `last_data_date`, per-file write times. Same rule as the `status --max-age` cron gate. |
+| `get_freshness` | How current the export is: `stale` judged on the core files (daily cache, sleep sessions) against a stated threshold (26 h by default, `HEALTH_STALE_AFTER_HOURS`, or `maxAgeHours`), `age_hours`, `as_of`, `last_data_date`, per-file write times. `state: "stale_copy"` (with a `stale_copy` list) when the phone's `.health-manifest.json` or iCloud says this Mac holds an older copy of a core file than the phone wrote. Same rule as the `status --max-age` cron gate. |
 | `list_metrics` | Every available metric with unit, day count, and date range. |
-| `get_health_metrics` | Daily values for a metric (or all) over a date range + an aggregate (avg/sum/min/max/latest). Supports `filterDays` (restrict to days covered by logged events, with `negate`). |
+| `get_health_metrics` | Daily values for a metric (or all) over a date range + an aggregate (avg/sum/min/max/latest). Supports `filterDays` (restrict to days covered by logged events, with `negate`). Blood pressure at day granularity also lists the individual `readings` (`health-readings.json`). |
 | `get_trends` | Recent N-day window vs the prior N days: change, % change, direction. Supports `excludeTravelDays`. |
 | `compare_periods` | A metric across two arbitrary date periods (A vs B), or around a logged event via `anchor: {eventId, days}` (the event day excluded from both sides). |
 | `get_structured_export` | Clean JSON for chosen metrics/range, paginated with a cursor. |
-| `get_intraday` | Today's hour-by-hour window from the app's hourly automations (`health-intraday.json`, app 1.4+), replaced each run. |
+| `get_intraday` | The hour-by-hour window from the app's hourly automations (`health-intraday.json`, app 1.4+): yesterday and today, replaced each run, with each hour's `Min`/`Max` for discrete metrics when the app writes them. |
 | `query_health_data` | Natural-language convenience: *"average HRV last month"* routed to structured results. |
-| `list_events` | Logged context events (medication, habit, visit, life, shift, episode, travel) with type/tag/date filters. |
+| `list_events` | Logged context events (medication, habit, visit, life, shift, episode, travel) with type/tag/date filters, from the app and from `add_event`, each labelled `source: "app"` or `"agent"`. |
+| `add_event` | Log an event the user states (a medication start, a trip) into `health-events-agent.json`, the one file this server writes. Idempotent by `clientEventId`. |
+| `remove_event` | Remove an event logged with `add_event`. Events logged in the iOS app are edited there. |
 | `get_profile` | Opted-in context fields (conditions, medications, goals, allergies, notes) plus `presentFields`. Absent fields were withheld, never "none". |
 | `get_workouts` | Workouts by activity/date with pagination; includes heart rate, running dynamics, cycling power, intervals and `hasRoute` when exported. |
-| `get_sleep_sessions` | Clustered sleep sessions attributed to the waking day; split nights returned as-is. |
+| `get_sleep_sessions` | Clustered sleep sessions attributed to the waking day; split nights returned as separate sessions, duplicate copies of one night collapsed (`collapsedDuplicates`). |
 | `get_cycle_context` | Day-in-cycle and coarse phase derived from logged period starts. Never predictive. |
 | `correlate_metrics` | Pearson correlation between two metrics with a 0..3 day lag. Association, not causation, always stated. |
 | `resolve_metric` | Canonical name and unit for any spelling (`steps`, `StepCount`, `Body Weight`, `hrv`), unit variants with exact formulas, an optional `{value, unit}` conversion, and whether the export holds it. Ambiguous words come back with candidates, never guessed. The data tools accept the same aliases and report `resolvedFrom`. When the export carries per-source attribution (app builds that write `src`/`by` on daily points and a `health-sources.json`, cache schema minor 2), the answer adds a `sources` block naming the devices that fed the export, which one won each metric and the priority rules, and `sourceMerge` reports disagreement as visible; older exports report it as not available. |
@@ -171,9 +171,9 @@ Full reference with request/response examples: **[healthexport.dev/mcp](https://
 
 ### Data files
 
-The daily cache (`.health-cache.json`) and workouts cache are joined by optional context files, all read-only and all optional: `health-events.json` (the logging surface), `health-profile.json` (opt-in context), `health-sessions.json` (sleep sessions), `health-cycles.json` (observed cycle starts), `health-days.json` (timezone change log). An absent file is reported as `available:false` with a note, never as "no data". Formats: [docs/SCHEMA-CONTRACTS.md](docs/SCHEMA-CONTRACTS.md).
+The daily cache (`.health-cache.json`) and workouts cache are joined by optional context files, all optional: `health-events.json` (the logging surface), `health-profile.json` (opt-in context), `health-sessions.json` (sleep sessions), `health-cycles.json` (observed cycle starts), `health-days.json` (timezone change log), `health-readings.json` (individual blood pressure readings) and `.health-manifest.json` (what the phone last wrote, for the stale-copy check). The server reads all of them and writes only `health-events-agent.json` (events logged with `add_event`). An absent file is reported as `available:false` with a note, never as "no data". Formats: [docs/SCHEMA-CONTRACTS.md](docs/SCHEMA-CONTRACTS.md).
 
-Two patterns worth knowing: [query a parent's Apple Health from your own AI](docs/caregiver-setup.md) (consent-first, the parent's phone is the authority) and [logging data into Apple Health via Shortcuts](docs/shortcuts-write-bridge.md) (the server and app stay strictly read-only).
+Two patterns worth knowing: [query a parent's Apple Health from your own AI](docs/caregiver-setup.md) (consent-first, the parent's phone is the authority) and [logging data into Apple Health via Shortcuts](docs/shortcuts-write-bridge.md) (the server never writes to Apple Health).
 
 ### MCP prompts
 
@@ -187,7 +187,7 @@ The server ships 22 prompts over `prompts/list` / `prompts/get`: daily brief, we
 
 ```bash
 node server.mjs --doctor            # diagnostics: files, sizes, schema, freshness, pairing
-node server.mjs status --max-age 24 # exit 0 if data is fresh, 1 if stale (cron gate)
+node server.mjs status --max-age 24 # exit 0 if data is fresh, 1 if stale or a stale iCloud copy (cron gate)
 node server.mjs receive             # standalone LAN receiver (binds 127.0.0.1 by default)
 node server.mjs --help
 ```
@@ -251,7 +251,7 @@ with exactly two shapes: `{"state": "trial", "daysRemaining": N}` or `{"state":
 export from a trial adds one sentence to `get_freshness` naming when the trial ends; an unlocked export
 adds nothing. No network call is involved and nothing is sent anywhere.
 
-- **Read-only.** The server only reads your exported data, it never touches HealthKit and never writes back.
+- **Reads your export, never Apple Health.** The server never touches HealthKit. Its only write is `health-events-agent.json`, the events an agent logs with `add_event` / `remove_event`; it never modifies a file the app writes. Both tools are refused in demo mode and on a read-only folder, and the file is sealed like the rest of an encrypted export.
 - **Local-first.** It runs on your machine over stdio. There is **no developer server** in the path.
 - **Optional pairing.** Set `PAIRING_SECRET` to the code the iOS app shows (Settings → Agent pairing) to gate access.
 - **Encrypted exports (optional).** If you switch on Export encryption in the iOS app, set `HEALTH_EXPORT_PASSPHRASE` (or `HEALTH_EXPORT_PASSPHRASE_FILE`) to the same passphrase and the server decrypts on your machine. See [Encrypted exports](#encrypted-exports).
@@ -352,6 +352,7 @@ For your own data, yes: the server reads the file the MetricBridge app writes an
 - **"No metrics found":** run `npx -y health-export-mcp --doctor`. It prints the folder the server chose and why (`HEALTH_DATA_DIR`, the iCloud default on a Mac, or the current directory) and whether `.health-cache.json` is there. Confirm the app has exported at least once; `get_mcp_status` shows the same source and the latest date.
 - **Server not visible in the client:** run `npx -y health-export-mcp --doctor` in a terminal. If it works there, the client can't find `npx` (common for Claude Desktop with Node from nvm or Homebrew): use the `.mcpb`, or set `"command"` to the full path from `which npx`. Then fully quit and reopen the client.
 - **Exports stopped after a week:** the app's free trial ended. `get_freshness` reports the export as stale and links the unlock page; once the app is unlocked, exports resume with no change on this side.
+- **Answers miss last night, or `state: "stale_copy"`:** this Mac's iCloud Drive has an older copy of the export than the phone wrote. Wait a few minutes, or open the MetricBridge folder in iCloud Drive in Finder and choose Download Now on the file (Remove Download drops only this Mac's local copy, and it downloads again). `--doctor` lists each stale copy.
 - **Locked data error:** the export file is protected until first unlock after reboot; unlock your device once.
 
 ---
@@ -372,7 +373,7 @@ stdio transport (newline-delimited JSON-RPC 2.0), the universal MCP transport. O
 
 ## How it works
 
-The iOS app reads Apple Health (read-only) and writes a compact `.health-cache.json` (plus optional context files) to the destination you choose. This server reads those files and exposes the 16 tools above over MCP. No bridge, no Docker, no database: just files and stdio.
+The iOS app reads Apple Health (read-only) and writes a compact `.health-cache.json` (plus optional context files) to the destination you choose. This server reads those files and exposes the 18 tools above over MCP. No bridge, no Docker, no database: just files and stdio.
 
 ```
 Apple Health → MetricBridge (iOS) → .health-cache.json → health-export-mcp → MCP client → you
@@ -388,7 +389,7 @@ Other Apple Health MCP servers in the ecosystem, worth a look depending on your
 - **[the-momentum/apple-health-mcp-server](https://github.com/the-momentum/apple-health-mcp-server):** an MCP server for analyzing Apple Health data exported from the Health app.
 - **[HealthyApps/health-auto-export-mcp-server](https://github.com/HealthyApps/health-auto-export-mcp-server):** an MCP server for the Health Auto Export app's data.
 
-**How `health-export-mcp` differs:** the iPhone app keeps the export current in the background, so there's no manual `export.xml` and no re-import; the server has zero dependencies and needs no Docker, database or Mac app; every answer carries its units, date range and coverage; and it's read-only end to end.
+**How `health-export-mcp` differs:** the iPhone app keeps the export current in the background, so there's no manual `export.xml` and no re-import; the server has zero dependencies and needs no Docker, database or Mac app; every answer carries its units, date range and coverage; and it never writes to Apple Health: its only write is the events file your agent logs to.
 
 ---
 

package/events.mjs

@@ -2,6 +2,8 @@
 // (docs/SCHEMA-CONTRACTS.md is the authoritative contract):
 //
 //   health-events.json    the one logging surface (medication, habit, visit, life, shift, episode, travel, other)
+//   health-events-agent.json  events an agent logged with add_event (contract section 10.2); this is
+//                         the ONE file this server writes, and only through add_event / remove_event
 //   health-profile.json   per-field opt-in context the user chose to share
 //   health-sessions.json  clustered sleep sessions, attributed to the WAKING day
 //   health-cycles.json    user-logged menstrual cycle starts (observed only, never predictive)
@@ -18,8 +20,11 @@
 // helpers out would mean relocating DATA_DIR resolution, which healthstore.test.mjs pins by
 // setting HEALTH_DATA_DIR before import.
 
-import { readJSONCached, assertUnlocked, assertDay, dataPath } from './healthstore.mjs';
+import fs from 'node:fs';
+import crypto from 'node:crypto';
+import { readJSONCached, assertUnlocked, assertDay, dataPath, encryptionStatus } from './healthstore.mjs';
 import { DEMO, demoData } from './demo.mjs';
+import { sealEnvelope, configuredPassphrase, EnvelopeError } from './envelope.mjs';
 
 export const KNOWN_EVENT_TYPES = ['medication', 'habit', 'visit', 'life', 'shift', 'episode', 'travel', 'other'];
 // Range events describe a STATE that covers days (a shift block, a trip, an episode). They are not
@@ -27,6 +32,10 @@ export const KNOWN_EVENT_TYPES = ['medication', 'habit', 'visit', 'life', 'shift
 const RANGE_TYPES = new Set(['shift', 'travel', 'episode']);
 
 const EVENTS_FILE = 'health-events.json';
+// The app owns health-events.json and replaces it whole on every export, so an agent writing into
+// it would be overwritten (or, through iCloud, conflict per FILE, not per record). Agent events
+// live in their own file with exactly one writer: this server.
+export const AGENT_EVENTS_FILE = 'health-events-agent.json';
 const PROFILE_FILE = 'health-profile.json';
 const SESSIONS_FILE = 'health-sessions.json';
 const CYCLES_FILE = 'health-cycles.json';
@@ -54,6 +63,24 @@ export function loadEventsFile() {
   return raw && Array.isArray(raw.events) ? raw : null;
 }
 
+/** The parsed agent events file, or null when absent/corrupt. A sealed file without its passphrase
+ *  throws the same explainable EnvelopeError every other reader does. */
+export function loadAgentEventsFile() {
+  if (DEMO) return null;
+  const raw = readJSONCached(dataPath(AGENT_EVENTS_FILE), null);
+  return raw && Array.isArray(raw.events) ? raw : null;
+}
+
+/** Every logged event from BOTH files, each labelled `source: "app" | "agent"`, or null when
+ *  neither file exists (callers surface that as unavailable, never as an empty match). */
+export function loadAllEvents() {
+  const app = loadEventsFile();
+  const agent = loadAgentEventsFile();
+  if (!app && !agent) return null;
+  const label = (source) => (e) => (e && typeof e === 'object' ? { ...e, source } : e);
+  return [...(app?.events ?? []).map(label('app')), ...(agent?.events ?? []).map(label('agent'))];
+}
+
 export function loadDaysFile() {
   if (DEMO) return demoData().days;
   const raw = readJSONCached(dataPath(DAYS_FILE), null);
@@ -95,10 +122,11 @@ export function eventDays(e) {
 /** The set of days covered by events matching {eventType, eventTag}. Null when the file is absent,
  *  which callers must surface honestly rather than treating as an empty match. */
 export function matchingEventDaySet({ eventType, eventTag } = {}) {
-  const file = loadEventsFile();
-  if (!file) return null;
+  const events = loadAllEvents();
+  if (!events) return null;
   const days = new Set();
-  for (const e of file.events) {
+  for (const e of events) {
+    if (!e || typeof e !== 'object') continue;
     if (eventType && e.type !== eventType) continue;
     if (eventTag && !(Array.isArray(e.tags) && e.tags.includes(eventTag))) continue;
     for (const d of eventDays(e)) days.add(d);
@@ -123,11 +151,11 @@ export function travelDaySet() {
  *  know are INCLUDED: an unknown type written by a newer app is more likely an intervention we
  *  cannot classify than noise, and silently ignoring it would hide a real segment. */
 export function boundariesIn(start, end) {
-  const file = loadEventsFile();
-  if (!file) return null;
+  const events = loadAllEvents();
+  if (!events) return null;
   const boundaryType = (t) => t === 'medication' || t === 'habit' || t === 'life' || t === 'other'
     || !KNOWN_EVENT_TYPES.includes(t);
-  return file.events
+  return events
     .filter((e) => e?.date && !e.endDate && boundaryType(e.type)
       && (!start || e.date >= start) && (!end || e.date <= end))
     .map((e) => ({ date: e.date, type: e.type, title: e.title ?? null }))
@@ -137,11 +165,11 @@ export function boundariesIn(start, end) {
 export const SEGMENT_NOTE = (n) =>
   `The window spans ${n} logged event(s). An average across a boundary can be a number that was true on no actual day; consider compare_periods anchored at the event date.`;
 
-/** Find one event by id. Returns {available:false} | {available:true, event|null}. */
+/** Find one event by id, in either file. Returns {available:false} | {available:true, event|null}. */
 export function findEvent(id) {
-  const file = loadEventsFile();
-  if (!file) return { available: false, event: null };
-  return { available: true, event: file.events.find((e) => e?.id === id) ?? null };
+  const events = loadAllEvents();
+  if (!events) return { available: false, event: null };
+  return { available: true, event: events.find((e) => e?.id === id) ?? null };
 }
 
 // ---- tool-level answers ----------------------------------------------------
@@ -151,13 +179,13 @@ export async function listEvents({ type, tag, start, end } = {}) {
   start = assertDay(start, 'start');
   end = assertDay(end, 'end');
   if (start && end && start > end) throw new Error(`start (${start}) is after end (${end})`);
-  const file = loadEventsFile();
-  if (!file) {
-    return absent(EVENTS_FILE, 'Events appear when the iOS app (1.5 or later) logs one (medication start, habit change, visit, shift block, trip) and exports.');
+  const all = loadAllEvents();
+  if (!all) {
+    return absent(EVENTS_FILE, 'Events appear when the iOS app (1.5 or later) logs one (medication start, habit change, visit, shift block, trip) and exports, or when an agent logs one with add_event.');
   }
   // Unknown types pass through unharmed: no allowlist here. A type filter matches the stored
   // string exactly, so a newer app's types remain reachable by name.
-  let events = file.events.filter((e) => e && typeof e.date === 'string');
+  let events = all.filter((e) => e && typeof e.date === 'string');
   if (type) events = events.filter((e) => e.type === type);
   if (tag) events = events.filter((e) => Array.isArray(e.tags) && e.tags.includes(tag));
   // A range event is "in" the window when it OVERLAPS it, matching how its days are counted.
@@ -173,12 +201,200 @@ export async function listEvents({ type, tag, start, end } = {}) {
     count: events.length,
     knownTypes: KNOWN_EVENT_TYPES,
     events,
+    sourceNote: 'source "app" events were logged in the MetricBridge iOS app (edit them there); source "agent" events were logged with add_event and can be removed with remove_event.',
     ...(events.length === 0 && {
       note: 'No events matched. The file is present; nothing matching this filter has been logged.',
     }),
   };
 }
 
+// ---- agent-logged events: the server's only write path (contract section 10.2) -------------
+// add_event / remove_event write health-events-agent.json and nothing else. Every write takes an
+// exclusive lock file, writes a temp file in the same folder and renames it over the target, so a
+// reader (this server, the iOS app, iCloud) only ever sees a whole file. Both temp and lock names
+// end in ".nosync", which iCloud Drive does not upload: neither ever reaches the phone.
+
+const LOCK_FILE = `.${AGENT_EVENTS_FILE}.lock.nosync`;
+const LOCK_STALE_MS = 30000;      // a crashed writer's lock is reclaimed after this long
+const LOCK_WAIT_MS = 3000;        // a live one is waited for at most this long
+const TITLE_MAX = 200, NOTE_MAX = 2000, TAG_MAX = 64, TAGS_MAX = 20, CLIENT_ID_MAX = 128;
+const ADD_KEYS = ['date', 'type', 'title', 'endDate', 'note', 'tags', 'clientEventId'];
+
+const sleepMs = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+
+/** Run `fn` holding the agent-events lock. Always released, also when `fn` throws. */
+function withAgentLock(fn) {
+  const lock = dataPath(LOCK_FILE);
+  const deadline = Date.now() + LOCK_WAIT_MS;
+  let fd;
+  for (;;) {
+    try { fd = fs.openSync(lock, 'wx', 0o600); break; }
+    catch (e) {
+      if (e.code !== 'EEXIST') throw new Error(`Could not lock ${AGENT_EVENTS_FILE} for writing (${e.code || 'error'}).`);
+      let age;
+      try { age = Date.now() - fs.statSync(lock).mtimeMs; } catch { continue; }   // released meanwhile
+      if (age > LOCK_STALE_MS) { try { fs.unlinkSync(lock); } catch {} continue; }
+      if (Date.now() > deadline) throw new Error(`Another add_event or remove_event is writing ${AGENT_EVENTS_FILE} right now. Try again in a moment.`);
+      sleepMs(25);
+    }
+  }
+  try {
+    try { fs.writeSync(fd, `${process.pid}\n`); } catch {}
+    return fn();
+  } finally {
+    try { fs.closeSync(fd); } catch {}
+    try { fs.unlinkSync(lock); } catch {}
+  }
+}
+
+/** Refuse to write where a write would be wrong: demo mode, a locked pairing gate, a folder that
+ *  holds no export, a read-only folder, or an encrypted export whose passphrase this server lacks
+ *  (writing that event in plaintext beside sealed files would leak exactly what the user sealed).
+ *  Returns the passphrase to seal with, or null for a plaintext destination. */
+const assertNotDemo = (tool) => {
+  if (DEMO) throw new Error(`${tool} is disabled in demo mode: there is no real export to write to. Restart without --demo to log events.`);
+};
+
+function assertWritable(tool) {
+  assertNotDemo(tool);
+  assertUnlocked();
+  const dir = dataPath('');
+  const has = (f) => { try { return fs.statSync(dataPath(f)).isFile(); } catch { return false; } };
+  if (!has('.health-cache.json') && !has(EVENTS_FILE) && !has(AGENT_EVENTS_FILE)) {
+    throw new Error(`${tool} writes beside a MetricBridge export, and ${dir} holds none (no .health-cache.json). Point HEALTH_DATA_DIR at the export folder, or log the event in the iOS app.`);
+  }
+  try { fs.accessSync(dir, fs.constants.W_OK); }
+  catch { throw new Error(`The data folder ${dir} is not writable by this server, so ${tool} cannot save anything there. Log the event in the MetricBridge iOS app instead.`); }
+  if (!encryptionStatus().encrypted) return null;
+  let passphrase = null;
+  try { passphrase = configuredPassphrase(); } catch { passphrase = null; }
+  if (!passphrase) {
+    throw new Error(`This export is encrypted and HEALTH_EXPORT_PASSPHRASE is not set, so ${tool} cannot seal the event like the rest of the export and will not write it in plaintext. Set the passphrase from the iOS app, or log the event in the app.`);
+  }
+  // The passphrase must open the export it will seal beside; a wrong one would write a file the
+  // app cannot read. Reading the cache verifies it (memoized, so this is free after first use).
+  try { readJSONCached(dataPath('.health-cache.json'), null); }
+  catch (e) { if (e instanceof EnvelopeError) throw new Error(`${tool}: ${e.message}`); throw e; }
+  return passphrase;
+}
+
+/** Replace health-events-agent.json atomically with `events`. Temp file in the same folder, renamed
+ *  over the target; the temp file is removed if anything fails. */
+function writeAgentEvents(events, passphrase) {
+  const body = JSON.stringify({ schema: 1, writer: 'health-export-mcp', writtenAt: new Date().toISOString(), events }, null, 2);
+  const bytes = passphrase ? JSON.stringify(sealEnvelope(body, passphrase)) : body;
+  const tmp = dataPath(`.${AGENT_EVENTS_FILE}.${process.pid}-${crypto.randomBytes(6).toString('hex')}.tmp.nosync`);
+  try {
+    const fd = fs.openSync(tmp, 'wx', 0o600);
+    try { fs.writeSync(fd, bytes); fs.fsyncSync(fd); } finally { fs.closeSync(fd); }
+    fs.renameSync(tmp, dataPath(AGENT_EVENTS_FILE));
+  } catch (e) {
+    try { fs.unlinkSync(tmp); } catch {}
+    throw new Error(`Could not write ${AGENT_EVENTS_FILE} (${e.code || e.message}). Nothing was changed.`);
+  }
+}
+
+const optString = (v, label, max) => {
+  if (v === undefined || v === null) return undefined;
+  if (typeof v !== 'string') throw new Error(`${label} must be a string`);
+  const t = v.trim();
+  if (!t) return undefined;
+  if (t.length > max) throw new Error(`${label} is ${t.length} characters; the limit is ${max}`);
+  return t;
+};
+
+/** Validate add_event's arguments strictly: an agent must learn its argument was wrong, never have
+ *  it silently coerced into an event the user did not mean. */
+function validateNewEvent(args) {
+  if (!args || typeof args !== 'object' || Array.isArray(args)) throw new Error('add_event takes an object: {date, type, title, endDate?, note?, tags?, clientEventId?}');
+  const unknown = Object.keys(args).filter((k) => !ADD_KEYS.includes(k));
+  if (unknown.length) throw new Error(`add_event does not take ${unknown.map((k) => `"${k}"`).join(', ')}. Fields: ${ADD_KEYS.join(', ')}.`);
+  const date = assertDay(args.date, 'date');
+  if (!date) throw new Error('date is required (YYYY-MM-DD, the local day the event happened or started)');
+  if (!KNOWN_EVENT_TYPES.includes(args.type)) {
+    throw new Error(`type must be one of ${KNOWN_EVENT_TYPES.join(', ')} (got ${JSON.stringify(args.type)})`);
+  }
+  const title = optString(args.title, 'title', TITLE_MAX);
+  if (!title) throw new Error('title is required: a short description, e.g. "Started magnesium"');
+  const endDate = assertDay(args.endDate, 'endDate');
+  if (endDate && endDate < date) throw new Error(`endDate (${endDate}) is before date (${date})`);
+  const note = optString(args.note, 'note', NOTE_MAX);
+  let tags;
+  if (args.tags !== undefined && args.tags !== null) {
+    if (!Array.isArray(args.tags)) throw new Error('tags must be an array of strings');
+    if (args.tags.length > TAGS_MAX) throw new Error(`at most ${TAGS_MAX} tags`);
+    tags = [...new Set(args.tags.map((t, i) => {
+      const v = optString(t, `tags[${i}]`, TAG_MAX);
+      if (!v) throw new Error(`tags[${i}] must be a non-empty string`);
+      return v;
+    }))];
+    if (!tags.length) tags = undefined;
+  }
+  const clientEventId = optString(args.clientEventId, 'clientEventId', CLIENT_ID_MAX);
+  return { date, type: args.type, title, endDate, note, tags, clientEventId };
+}
+
+/** add_event: log one event into health-events-agent.json. Idempotent: the same clientEventId (or,
+ *  without one, the same date, type, title and endDate) returns the event already logged. */
+export async function addEvent(args = {}) {
+  assertNotDemo('add_event');
+  const v = validateNewEvent(args);
+  const passphrase = assertWritable('add_event');
+  return withAgentLock(() => {
+    const events = [...(loadAgentEventsFile()?.events ?? [])];
+    const same = v.clientEventId
+      ? (e) => e?.clientEventId === v.clientEventId
+      : (e) => !e?.clientEventId && e?.date === v.date && e?.type === v.type && e?.title === v.title && (e?.endDate ?? undefined) === v.endDate;
+    const existing = events.find(same);
+    if (existing) {
+      return {
+        added: false, duplicate: true, file: AGENT_EVENTS_FILE, event: { ...existing, source: 'agent' },
+        note: v.clientEventId
+          ? `An event with clientEventId "${v.clientEventId}" is already logged, so nothing was added.`
+          : 'An identical event (same date, type, title and endDate) is already logged, so nothing was added. Pass a distinct clientEventId to log a second one on purpose.',
+      };
+    }
+    const event = {
+      id: `agent-${crypto.randomUUID()}`,
+      date: v.date, type: v.type, title: v.title,
+      ...(v.endDate && { endDate: v.endDate }),
+      ...(v.note && { note: v.note }),
+      ...(v.tags && { tags: v.tags }),
+      createdAt: new Date().toISOString(),
+      ...(v.clientEventId && { clientEventId: v.clientEventId }),
+    };
+    writeAgentEvents([...events, event], passphrase);
+    return {
+      added: true, file: AGENT_EVENTS_FILE, event: { ...event, source: 'agent' },
+      note: `Logged in ${AGENT_EVENTS_FILE} beside the export. list_events, compare_periods anchors and filterDays read it at once; the iOS app shows it read-only. Remove it with remove_event and this id.`,
+    };
+  });
+}
+
+/** remove_event: delete one agent-logged event. App events are refused (they belong to the app,
+ *  which rewrites its own file). Removing an id that is already gone is a no-op, not an error. */
+export async function removeEvent(args = {}) {
+  assertNotDemo('remove_event');
+  if (!args || typeof args !== 'object' || Array.isArray(args)) throw new Error('remove_event takes {id}');
+  const unknown = Object.keys(args).filter((k) => k !== 'id');
+  if (unknown.length) throw new Error(`remove_event takes only "id" (got ${unknown.map((k) => `"${k}"`).join(', ')})`);
+  const id = typeof args.id === 'string' ? args.id.trim() : '';
+  if (!id) throw new Error('id is required: the event id from list_events or add_event');
+  if (!id.startsWith('agent-')) {
+    throw new Error(`"${id}" is not an agent-logged event. Only events added with add_event (ids starting "agent-", source "agent" in list_events) can be removed here; events logged in the MetricBridge iOS app are edited or deleted in the app.`);
+  }
+  const passphrase = assertWritable('remove_event');
+  return withAgentLock(() => {
+    const events = loadAgentEventsFile()?.events ?? [];
+    const existing = events.find((e) => e?.id === id);
+    if (!existing) {
+      return { removed: false, id, file: AGENT_EVENTS_FILE, note: `No agent-logged event has id "${id}" (already removed, or never added). Nothing was changed.` };
+    }
+    writeAgentEvents(events.filter((e) => e?.id !== id), passphrase);
+    return { removed: true, id, file: AGENT_EVENTS_FILE, event: { ...existing, source: 'agent' } };
+  });
+}
+
 export async function getProfile() {
   assertUnlocked();
   const file = loadProfileFile();
@@ -211,15 +427,49 @@ export async function getSleepSessions({ start, end, day } = {}) {
   if (day) sessions = sessions.filter((s) => s.day === day);
   if (start) sessions = sessions.filter((s) => s.day >= start);
   if (end) sessions = sessions.filter((s) => s.day <= end);
-  sessions = [...sessions].sort((a, b) => String(a.start).localeCompare(String(b.start)));
+  const { kept, collapsed } = collapseDuplicateSessions(sessions);
+  sessions = kept.sort((a, b) => String(a.start).localeCompare(String(b.start)));
+  const manualInBed = sessions.filter((s) => s.manualInBed === true).length;
   return {
     available: true,
     count: sessions.length,
+    ...(collapsed > 0 && { collapsedDuplicates: collapsed }),
+    ...(manualInBed > 0 && { manualInBedSessions: manualInBed }),
     sessions,
-    note: 'Sessions are attributed to the WAKING day: a night from 23:00 on the 18th to 06:50 on the 19th belongs to day 2026-08-19, matching the daily cache\'s sleep_analysis attribution. Multiple sessions on one day are a split night, returned as-is; union the hours, never sum overlapping sessions.',
+    note: 'Sessions are attributed to the WAKING day: a night from 23:00 on the 18th to 06:50 on the 19th belongs to day 2026-08-19, matching the daily cache\'s sleep_analysis attribution. Separate sessions on one day are a split night, returned as separate rows; union the hours, never sum overlapping sessions.'
+      + (collapsed > 0 ? ` ${collapsed} duplicate session(s) were collapsed: rows that share an end time with, or sit entirely inside, a longer session on the same day are copies of one night written by older app versions, and only the longer one is kept.` : '')
+      + (manualInBed > 0 ? ` ${manualInBed} session(s) carry manualInBed:true: built from an "In Bed" entry the user typed into the Health app with no asleep sample from any device, counted as asleep.` : ''),
   };
 }
 
+/** Collapse copies of one night (contract section 10.5). Older app builds rebuilt a night from its
+ *  post-midnight half and stored it beside the full night: same waking day, same end, later start,
+ *  fewer hours. Within a waking day, a session that shares its end instant with a longer one, or
+ *  lies entirely inside one, is that copy; the longer survives. Sessions whose times do not parse
+ *  are never collapsed. A genuine split night (two sessions that do not overlap) is untouched. */
+function collapseDuplicateSessions(sessions) {
+  const byDay = new Map();
+  for (const s of sessions) {
+    if (!byDay.has(s.day)) byDay.set(s.day, []);
+    byDay.get(s.day).push({ s, a: Date.parse(s.start), b: Date.parse(s.end) });
+  }
+  const kept = [];
+  let collapsed = 0;
+  for (const group of byDay.values()) {
+    const span = (x) => (Number.isFinite(x.a) && Number.isFinite(x.b) ? x.b - x.a : -1);
+    group.sort((x, y) => span(y) - span(x) || (Number(y.s.hours) || 0) - (Number(x.s.hours) || 0));
+    const survivors = [];
+    for (const x of group) {
+      const timed = Number.isFinite(x.a) && Number.isFinite(x.b);
+      const dup = timed && survivors.some((k) => Number.isFinite(k.a) && Number.isFinite(k.b)
+        && (k.b === x.b || (x.a >= k.a && x.b <= k.b)));
+      if (dup) collapsed++; else survivors.push(x);
+    }
+    kept.push(...survivors.map((x) => x.s));
+  }
+  return { kept, collapsed };
+}
+
 // ---- cycle context ---------------------------------------------------------
 
 const CYCLE_BASIS = 'Derived from logged periods, not predictive. Phase labels are coarse: follicular from day 1 to the observed midpoint of that cycle (day 14 for the ongoing cycle, whose length is not yet observed), luteal for the remainder. No ovulation estimate is made.';