mercury-agent 0.18.2 → 0.19.0

package/docs/goals/rehearsal-bench/decisions.md

@@ -205,17 +205,55 @@
   the owner and a second WhatsApp account, with the snapshot/restore
   procedure of §5. The bench does not try to make this list empty.
 - **Alternatives considered:** a Baileys stub; a second bot number in
-  shadow mode.
+  shadow mode; **a test bot** — a snapshot restored on another host
+  (M1.6), the candidate Mercury version installed, linked to WhatsApp with
+  its *own* number, and driven from the owner's phone (owner's question,
+  2026-09-06).
 - **Reasoning:** the memory `mercury-member-role-cannot-be-simulated` and
   the F5 debug doc both record the same wall: `isSelfJid` reads a live socket.
   D-003 moves the *decisions* out from behind that wall; the socket itself is
   not our code and is not worth stubbing. A private lab group with a second
   account is cheap and is what the football space already is until the real
   group is linked.
+
+  The test bot is **complementary, not a replacement**, and it is not safe
+  as described. It exercises what the shadow cannot — the socket list
+  above — but a snapshot linked to a different number breaks on identity:
+  every space is reached through `conversations.external_id`, the live
+  chat JID (`src/storage/db.ts`, `conversations`), so the copied groups
+  belong to a bot that is not a member of them and the copied `main` space
+  points at the owner's real number. Three consequences, each of which
+  the shadow avoids by having no adapter at all: (1) a copied scheduled
+  task whose space resolves to the owner's DM **sends from the test number
+  to the owner's real phone**, and one bound to a group the test bot has
+  been added to reaches the group; (2) the test bot cannot be added to the
+  real groups without reaching real people, so it needs its own groups,
+  whose JIDs differ, so the copied roles, tasks, config and workspace no
+  longer apply until the snapshot's space→chat links are remapped; (3) D-002
+  makes "adapter on" mean "live", so every refusal of D-005 (broker,
+  publish, billing, deliver) is off — a copied task with a broker action is
+  real. What a test bot cannot do at all: act *as* a specific existing
+  member (a non-admin quoting a bot message is the F5 shape), which
+  `shadow say --as <member>` replays from the copied `space_roles`. What it
+  does better: everything in §5, plus a candidate version on a real socket
+  before `promote` (D-013). Where it is redundant: a migration rehearsal
+  (apply → diff) needs no socket and is the shadow's own job (M1.4, M3.2).
 - **Revisit if:** the owner does not want to hold a second number — then the
   §5 list becomes the standing content of `pending-verification.md` and the
-  bench's coverage is everything else.
-- **Used by:** lab-space-procedure
+  bench's coverage is everything else. **Or** the owner wants the test bot —
+  then it is M4.2 and lands only with all three preconditions, each denying
+  on absence: a new opt-in mode value (never "`MERCURY_SHADOW` unset plus a
+  list" — absence is live, D-002) that keeps every D-005 refusal while
+  constructing the adapter; a **recipient allowlist** of literal chat JIDs
+  on the send side (none exists today — `direct-send.ts` resolves a
+  recipient, it does not restrict one), checked at the bridge so all
+  fifteen send sites of `docs/live-testing.md` §3 are behind it, empty
+  list = nothing leaves; and a `shadow snapshot --remap <live-jid>=<test-jid>`
+  that rewrites `conversations.external_id` (and `message_platform_ids`)
+  so the copied spaces point at the test groups, refusing any live JID left
+  unmapped. Tasks whose space maps to nothing are deactivated in the copy,
+  not left to fail silently.
+- **Used by:** lab-space-procedure; test-bot-instance (M4.2, if chosen)
 
 ## D-008: No injection route on the live instance in this goal
 - **Category:** scope

package/docs/goals/rehearsal-bench/roadmap.md

@@ -1,7 +1,7 @@
 # Roadmap: Rehearsal Bench
 
 **Goal**: [rehearsal-bench](goal.md)
-**Last updated**: 2026-09-03 (re-scope after the VPS cutover review, [note](../../notes/2026-09-03-release-gate-and-test-environment.md):
+**Last updated**: 2026-09-06 (M4.2 `test-bot-instance` added as an owner's-decision story after the "why not a test bot on a snapshot?" review — D-007 extended with the identity/egress/remap analysis; nothing else moved). Earlier: 2026-09-03 (re-scope after the VPS cutover review, [note](../../notes/2026-09-03-release-gate-and-test-environment.md):
 M1.3 gains the instance-label prerequisite and the fleet-box shape; M1.6
 `snapshot-across-hosts` added; M3.2 extended to tagula's space-sync path;
 M3.3 `sync-rehearse` **moved** to [`release-gate`](../release-gate/roadmap.md)
@@ -99,6 +99,7 @@ in `pending-verification.md` for that fix is replaced by the transcript.
 | ID | Story | Slug | Depends on | Status |
 |----|-------|------|------------|--------|
 | M4.1 | `lab` space: private group of bot + owner + second account; `mercury lab snapshot|restore` = `VACUUM INTO` + tar before, `messages`/`space_roles`/`token_usage` window delete + workspace restore after; `restore` proves itself by re-running `shadow diff` against the pre-snapshot and requiring an empty report | lab-space-procedure | M1.4 | backlog (needs a second WhatsApp number — owner's decision) |
+| M4.2 | **Test-bot instance** (added 2026-09-06, D-007 revisit): a snapshot restored on another host (M1.6) and linked to WhatsApp with its own number, driven from the owner's phone — the socket-only list of §5 on a candidate version, before `promote`. Complementary to the shadow, never a replacement (it cannot act *as* an existing member; a migration rehearsal needs no socket). Lands only with three guards, each denying on absence: a new opt-in mode that constructs the adapter but keeps every D-005 refusal (absence is still live, D-002); a send-side **recipient allowlist** of literal chat JIDs checked at the bridge behind all §3 send sites, empty = nothing leaves; `shadow snapshot --remap <live-jid>=<test-jid>` rewriting `conversations.external_id` + `message_platform_ids`, refusing an unmapped live JID and deactivating tasks whose space maps to nothing. Without the remap a copied task delivers from the test number to the owner's real DM | test-bot-instance | M1.6, M1.4 | backlog (needs a second bot number and a host — owner's decision) |
 
 **Checkpoint:** the §5 list of `docs/live-testing.md` is walked once in the
 lab space and every item is either ticked with the date or moved into M2 as
@@ -153,6 +154,7 @@ M1.1 ─ M1.5         │
 M2.1 ──────┬─ M2.2 ─┴─ M2.3 ─ M2.4
 M1.3 ──────┘   └────────────────────► release-gate R3 (smoke runner)
 M1.4 ─ M4.1
+M1.6 ─ M4.2 (owner's decision)
 release-gate R5 (sync-rehearse, ex-M3.3) ◄─ M3.1, M2.3
 ```
 

package/docs/goals/release-gate/decisions.md

@@ -110,3 +110,43 @@
 - **Revisit if:** a second operator (not tagula) needs the same policy —
   then it is a Mercury feature, planned as one.
 - **Used by:** smoke-runner, release-gate-rules
+
+## G-007: Whether Mercury publishes its own agent image — OPEN, owner's call
+- **Category:** architecture / distribution
+- **Status:** **Open.** R0.3 is blocked on it; R0.1, R0.2 and R0.5 are not.
+- **Question:** Mercury's release workflow publishes the npm package and
+  nothing else. The agent image every fleet box runs is built and pushed by
+  `agent-image.yml` in **tagula-agents**, from Mercury's published npm
+  tarball. Mercury's own `ghcr.io/avishai-tsabari/mercury-agent` is pushed
+  by hand (`docs/runbooks/publish-checklist.md`, "manual — CI does not do
+  this"), is stale, and returned 401/403 unauthenticated on 2026-09-05.
+  Should Mercury publish its own image from `release.yml`, and public or
+  private?
+- **Evidence (2026-09-05):** `container/Dockerfile` has zero `LABEL` lines;
+  `container/build.sh:20` tags `:latest` only; `release.yml` has no
+  `packages: write`; `src/config.ts:59` defaults to
+  `ghcr.io/avishai-tsabari/mercury-agent:latest`;
+  `container-runner.ts:1131-1136` never refreshes a tag that exists locally;
+  `container-runner.ts:1104-1117` skips validation for exactly the
+  `/mercury-agent:` names that broke. A fresh outside install therefore
+  fails `ensureImage()` and must fall back to a ~2.8 GB local `mercury build`
+  the README's install steps never mention. The tagula box could not perform
+  that fallback: 2 vCPU, 3 GB RAM and 1.9 GB free before the 2026-09-05
+  cleanup.
+- **The two answers, and what each commits to:**
+  - **Public.** One publishing path, third-party installs work, R0.4's
+    version pin becomes safe, `agent-image.yml`'s version-linking half
+    retires. Commits to publishing a built artifact of a private repo —
+    the same reason the fleet image is private — so it is an open-core
+    boundary decision, not a CI one.
+  - **Private (or no change).** Nothing outside the fleet can install
+    Mercury. Then say so: `docs/container-lifecycle.md:225` currently
+    claims "Images are published on each release", which is false today
+    either way, and the README's install steps imply an independent
+    install that does not exist.
+- **Not in scope of this decision:** the fleet's idle check, database
+  snapshot, rollback and stagger. Those are topology and stay in
+  tagula-agents whatever is decided here (G-006).
+- **Revisit if:** a second operator appears, or Mercury is open-sourced.
+- **Used by:** mercury-publishes-image (R0.3), image-refresh-and-visibility (R0.4)
+

package/docs/goals/release-gate/roadmap.md

@@ -1,7 +1,7 @@
 # Roadmap: Release Gate
 
 **Goal**: [release-gate](goal.md)
-**Last updated**: 2026-09-03 (created from the VPS cutover review; story slugs are `/f-feature-planning` inputs)
+**Last updated**: 2026-09-06 (R0 added: the image supply side R1.1(c) reads from, and nobody owned)
 
 > Order is by leverage against the live risk, not by size: R1 protects the
 > customer box within a session or two and depends on nothing; R2 is the
@@ -11,6 +11,33 @@
 
 ## Milestones
 
+### Milestone R0: The agent image is a published, self-describing artifact
+
+> R1.1(c) asks the image what mercury version it is and which `COPY`
+> sources it carries. **Nothing puts either there today**, and nothing in
+> this repo publishes the image at all, so R1.1(c) has no artifact to read
+> and no milestone owned the gap. This is that milestone. It is small,
+> it depends on nothing, and R1.1(c) is blocked without R0.1.
+>
+> Established 2026-09-05 while releasing 0.18.1/0.18.2 (evidence in
+> [`decisions.md` G-007](decisions.md)):
+> `container/Dockerfile` has **zero** `LABEL` lines; `container/build.sh`
+> tags `:latest` only, never a version; `release.yml` has no image job and
+> no `packages: write` anywhere; the image every fleet box actually runs is
+> built and pushed by `agent-image.yml` in **tagula-agents**, from
+> Mercury's published npm tarball. Mercury's own
+> `ghcr.io/avishai-tsabari/mercury-agent` is pushed by hand per
+> `docs/runbooks/publish-checklist.md` ("CI does not do this"), is stale,
+> and is **not anonymously pullable** (401/403 verified 2026-09-05).
+
+| ID | Story | Slug | Depends on | Status |
+|----|-------|------|------------|--------|
+| R0.1 | **The image describes itself.** `container/Dockerfile` + `container/build.sh` stamp, at build time, (a) `org.opencontainers.image.version` and a mercury-namespaced version label taken from `package.json`, not hand-typed, and (b) the **`COPY`-source manifest** R1.1(c) checks against — generated from the Dockerfile's own `COPY` list so the two cannot drift. `build.sh` tags `:<version>` as well as `:latest`. Labels are inherited by the derived `mercury-agent-ext-*` image with no builder change (verified on the tagula box 2026-09-05: derived and base both report `0.18.0-beta.0`), so the host-side check works through the image actually executing | image-self-describing | — | backlog — **blocks R1.1(c)** | 
+| R0.2 | **The build-integrity gate moves into this repo.** `agent-image.yml` in tagula-agents verifies Mercury's artifact — every `COPY` source present in the tarball, `bun build container-entry.ts` resolves inside the image — and that check is what would have caught 0.17.0. It belongs in `release.yml` (or `bun run check`) so every consumer building the image gets it, not only this one fleet. The fleet keeps its copy or drops it; either is fine once this exists | build-integrity-in-mercury | — | backlog |
+| R0.3 | **Mercury publishes its own image.** A job in `release.yml`, after `publish-npm`, that installs the published tarball, builds, verifies (R0.2) and pushes `:<version>` + `:latest` with the R0.1 labels. Needs `packages: write`, which no job has today. **Gated on the G-007 decision** (public or private): the answer changes whether this closes the third-party install path or only tidies the internal one. Makes `agent-image.yml`'s *version-linking* half redundant; its nightly updater, idle check, snapshot, rollback and stagger stay where they are | mercury-publishes-image | R0.1, R0.2, G-007 | backlog — **decision first** |
+| R0.4 | **A floating tag stops meaning "frozen at first pull".** `ensureImage()` returns the moment `docker image inspect` succeeds, so the default `:latest` is never refreshed and a host upgraded by npm keeps yesterday's container silently — the trap the owner hit on 2026-09-05. Either pin the default to `:${pkg.version}` (safe **only** after R0.3, or every fresh install fails on a tag nobody published) or re-pull a floating tag on a version change. Either way boot logs the resolved image ref, digest and version label so drift is visible without asking | image-refresh-and-visibility | R0.3 | backlog |
+| R0.5 | **`mercury upgrade` owns both halves.** `upgradeAction` contains no Docker call at all: it stops the service, npm-installs and restarts, leaving the image behind. It should pull the matching image first and refuse when that tag does not exist — image first, host second, the rule the fleet updater already follows and the one 0.17.0 broke | upgrade-pulls-image | R0.1 | backlog |
+
 ### Milestone R1: Preflight
 > After this, a box that cannot run a container says so at boot and on
 > demand, with one diagnosis per blocker, and the nightly updater has
@@ -94,6 +121,10 @@ manual check in `pending-verification.md` is replaced by the reports.
 ## Dependency Graph
 
 ```
+R0.1 ─┬─ R1.1(c)
+      ├─ R0.5
+      └─ R0.3 ◄─ G-007 (decision) ─ R0.4
+R0.2 ─── R0.3
 R1.1 ─┬─ R1.2
       ├─ R2.1 ─ R2.2
       ├─ R4.1 ─ R5.2
@@ -103,7 +134,9 @@ R3.1 ─ R3.2 ─┬─ R3.3
 rehearsal-bench M2.2 (function half) ─► R3.2
 ```
 
-R1.1 first, alone. R2 and R4 can run beside R3.1 in separate worktrees.
+R0.1 is the true first story: it is small, depends on nothing, and R1.1(c)
+cannot be built without it. R0.3 waits on a decision, not on code.
+R1.1 otherwise first, alone. R2 and R4 can run beside R3.1 in separate worktrees.
 R3.2 is the join with the bench. R5 last.
 
 ## Cost note

package/examples/extensions/gws/index.ts

@@ -15,6 +15,8 @@ type ConnectionAuthType =
   | "credentials-file"
   | "custom";
 
+type ConnectionStatus = "connected" | "needs-reauth" | "broken" | "unknown";
+
 type MercuryExt = {
   cli(opts: { name: string; install: string }): void;
   permission(opts: { defaultRoles: string[] }): void;
@@ -27,6 +29,7 @@ type MercuryExt = {
     authType: ConnectionAuthType;
     credentialEnvVar?: string;
     scopes?: string[];
+    statusCheck?: () => Promise<{ status: ConnectionStatus; detail?: string }>;
   }): void;
   on(
     event: "before_container",
@@ -55,6 +58,59 @@ const gwsEnv = {
 /** Path where credentials are materialized inside the inner container's own /tmp. */
 const CREDENTIALS_FILE = "/tmp/gws-credentials.json";
 
+/**
+ * The string fields google-auth-library needs on an ADC "authorized user"
+ * document, beyond `type`. `type` is checked separately so its absence can be
+ * named on its own — it is the field operators actually hit.
+ */
+const REQUIRED_CREDENTIAL_FIELDS = [
+  "client_id",
+  "client_secret",
+  "refresh_token",
+] as const;
+
+/**
+ * Describe what is wrong with a candidate credential, or `undefined` when it is
+ * a usable ADC "authorized user" document.
+ *
+ * A parse check is not enough, which is what this guard exists to fix. Google's
+ * `/token` response is valid JSON carrying a working `refresh_token`, but has no
+ * top-level `type`, so it sails through `JSON.parse` and then fails on *every*
+ * `gws` invocation with "the file doesn't contain the field 'type'" — from
+ * inside a conversation, where no operator sees it. `{}` passed too. Read the
+ * guard by asking what happens when a field is missing, and make absence deny.
+ */
+function credentialProblem(raw: string): string | undefined {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return "is not valid JSON";
+  }
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    return "is not a JSON object";
+  }
+  const doc = parsed as Record<string, unknown>;
+  if (doc.type === undefined) {
+    return 'is missing the "type" field (expected "authorized_user"; note that "token_type" is a different field and does not satisfy it)';
+  }
+  if (doc.type !== "authorized_user") {
+    return `has type ${JSON.stringify(doc.type)} (expected "authorized_user")`;
+  }
+  const missing = REQUIRED_CREDENTIAL_FIELDS.filter(
+    (field) => typeof doc[field] !== "string" || doc[field] === "",
+  );
+  if (missing.length > 0) {
+    return `is missing or has empty ${missing.join(", ")}`;
+  }
+  return undefined;
+}
+
+/** Appended to every rejection so the log names the fix, not just the fault. */
+const CREDENTIAL_RECOVERY =
+  'Expected {"type":"authorized_user","client_id":...,"client_secret":...,"refresh_token":...}. ' +
+  "Regenerate with: gws auth login && gws auth export --unmasked";
+
 export default function (mercury: MercuryExt) {
   // The gws CLI can only take refresh-token credentials from a file, so someone
   // has to materialize GWS_CREDENTIALS_JSON before the first command runs. The
@@ -81,11 +137,11 @@ export default function (mercury: MercuryExt) {
         "'if [ -n \"$GWS_CREDENTIALS_JSON\" ]; then' " +
         `'  c="\${GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE:-${CREDENTIALS_FILE}}"' ` +
         "'  t=\"$c.$$\"' " +
-        "'  (umask 077; printf %s \"$GWS_CREDENTIALS_JSON\" > \"$t\")' " +
+        '\'  (umask 077; printf %s "$GWS_CREDENTIALS_JSON" > "$t")\' ' +
         // Credentials changed (rotation, or a different caller in a reused
         // container) invalidates the cached access token alongside them.
-        "'  cmp -s \"$t\" \"$c\" 2>/dev/null || rm -f \"${GOOGLE_WORKSPACE_CLI_CONFIG_DIR:-$HOME/.config/gws}/token_cache.json\"' " +
-        "'  mv -f \"$t\" \"$c\"' " +
+        '\'  cmp -s "$t" "$c" 2>/dev/null || rm -f "${GOOGLE_WORKSPACE_CLI_CONFIG_DIR:-$HOME/.config/gws}/token_cache.json"\' ' +
+        '\'  mv -f "$t" "$c"\' ' +
         "'  GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=\"$c\"; export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE' " +
         "'fi' " +
         "'exec /usr/local/bin/gws-real \"$@\"' " +
@@ -112,21 +168,56 @@ export default function (mercury: MercuryExt) {
       "https://www.googleapis.com/auth/spreadsheets",
       "https://www.googleapis.com/auth/userinfo.email",
     ],
+    // Without this, the connection reports "connected" on presence alone, so a
+    // credential the CLI cannot use still shows green on the dashboard and the
+    // only symptom is a failed tool call mid-conversation. Shape is checked
+    // here — validity (is the token still live?) is not, and still has no
+    // reader; see docs/bugs/gws-connection-credential-has-no-health-check.md.
+    statusCheck: async () => {
+      const raw = process.env[gwsEnv.env.credentials];
+      // Match the runtime's own presence default so an unconfigured connection
+      // reads the same with or without this probe.
+      if (!raw) {
+        return {
+          status: "unknown",
+          detail: `${gwsEnv.env.credentials} is not set`,
+        };
+      }
+      const problem = credentialProblem(raw);
+      if (problem) {
+        return {
+          status: "broken",
+          detail: `${gwsEnv.env.credentials} ${problem}`,
+        };
+      }
+      return { status: "connected" };
+    },
   });
 
   // Inner containers don't share the outer container's volume — they mount host
   // filesystem paths. So we can't write a credentials file from this hook and
   // have the inner container see it. Instead, pass the target path via env var
   // and let the skill materialize the file from GWS_CREDENTIALS_JSON at runtime.
-  mercury.on("before_container", async () => {
+  mercury.on("before_container", async (event, ctx) => {
     const raw = process.env[gwsEnv.env.credentials];
     if (!raw) return undefined;
 
-    try {
-      JSON.parse(raw);
-    } catch {
+    // GWS_CREDENTIALS_JSON is delivered by THIS hook, not by mercury.env(), and
+    // the two paths are not gated alike: a declared env var is injected only for
+    // a caller holding the extension's permission, while a hook's returned env
+    // is merged in `emitBeforeContainer` and pushed straight onto the container's
+    // `-e` list with no RBAC in between. So `mercury.permission()` above gates
+    // the *skill*, not this credential — without the check here the refresh
+    // token (gmail.modify, drive, calendar, documents, spreadsheets) reaches
+    // every caller in every space. The permission name is the extension name.
+    if (!ctx.hasCallerPermission(event.spaceId, event.callerId, "gws")) {
+      return undefined;
+    }
+
+    const problem = credentialProblem(raw);
+    if (problem) {
       console.error(
-        `[gws.before_container] ${gwsEnv.env.credentials} is not valid JSON — skipping`,
+        `[gws.before_container] ${gwsEnv.env.credentials} ${problem} — skipping. ${CREDENTIAL_RECOVERY}`,
       );
       return undefined;
     }

package/examples/extensions/morning/README.md

@@ -41,22 +41,23 @@ mrctl config set morning.environment sandbox      # or: production
 
 Only those two values are accepted. A typo is refused at set time.
 
-## Two things that will look like bugs
+## Why this connection is not marked `sensitive`
 
-**1. In a WhatsApp group, every turn is blocked until you enable sensitive
-connections.** This connection is declared `sensitive: true` because it can
-issue legally binding tax documents. In a group-linked space Mercury then
-refuses assistant turns unless the space opts in, and asks each caller to
-confirm:
+It issues legally binding tax documents, so `sensitive: true` looks right. It is
+deliberately omitted, because the runtime's sensitive guard is host-global and
+space-blind: one sensitive connection anywhere on the host puts *every*
+group-linked space behind a per-message confirmation, and the confirmation is
+consumed on each `yes`, so it repeats for every turn forever. A host with one
+accounting space and thirteen unrelated ones would pay that cost fourteen times
+over.
 
-```bash
-mrctl config set security.sensitive_connections_allowed true
-```
+Nothing load-bearing is lost. The credentials are `hostOnly` and reached only
+through the broker, so they never enter an agent container, and the verbs are
+`admin`-only. Restore the flag once the guard scopes per-space or per-extension.
 
-This is intended, not a fault. In a one-to-one conversation the guard does not
-apply.
+## One thing that will look like a bug
 
-**2. Issuing requires a preview first.** `document-create` refuses without an
+**Issuing requires a preview first.** `document-create` refuses without an
 `issueToken` returned by `document-preview` of the *same* document. The token is
 bound to the payload, the environment, the space and the caller, and works once.
 A retry after a successful create is refused rather than issuing twice.
@@ -93,7 +94,16 @@ mrctl capability morning <action> '<json>'
 ```
 
 `client-search`, `client-create`, `document-types`, `document-preview`,
-`document-create`, `document-search`, `document-links`.
+`document-create`, `document-search`, `document-links`, `expense-upload`,
+`expense-draft-search`.
+
+**`expense-upload` takes a path, never bytes.** The container names a file
+relative to its own space workspace (`inbox/receipt.pdf`); the host reads it and
+confines the path to `<spacesDir>/<spaceId>/`, resolving symlinks *before* the
+containment check — `inbox/` is written by a lower-trust boundary, so a symlink
+there pointing at the host's `.env` is the attack the guard exists for. A
+refused path returns one generic message and logs the detail host-side at WARN;
+telling the container why would make the guard a filesystem oracle.
 
 Full request shapes and the issue flow are in `skill/SKILL.md`; enums and the
 240-row error table are in `skill/references/`.
@@ -102,8 +112,9 @@ Full request shapes and the issue flow are in `skill/SKILL.md`; enums and the
 
 | Area | Why |
 |---|---|
-| Expenses, receipt upload | `POST /expenses` requires an `accountingClassification`, and the "Get Accounting Classifications" endpoint its schema references is absent from the 53 published paths. Also, an uploaded file always becomes a *draft* and there is no API to approve a draft. |
-| Webhooks (`payment/received`, `document/created`) | Extensions cannot register HTTP routes. Needs a core route or a polling job. |
+| Creating an expense from typed-in details (`POST /expenses`) | Requires an `accountingClassification`, and the "Get Accounting Classifications" endpoint its schema references is still absent from the published paths (re-verified 2026-09-06). Classifying inline would mean guessing a tax category on the user's behalf. Receipt **upload** sidesteps this entirely and is implemented — it creates a draft Morning parses itself, which a human approves in Morning's UI. |
+| Editing, closing or deleting an expense | Reading and creating drafts is the chore; mutating existing expenses is a larger trust decision. |
+| Webhooks (`payment/received`, `document/created`, `expense-draft/parsed`) | Extensions cannot register HTTP routes. This is why `expense-upload` cannot report whether a draft was ultimately parsed or declined — poll `expense-draft-search` instead. |
 | Payments API, credit-card tokens | Moving money is a larger trust decision than issuing a document. |
 | Partners API | For multi-business accountants; this is scoped to one business per key set. |
 

package/examples/extensions/morning/index.ts

@@ -12,6 +12,7 @@
  * without an accounting-classification source.
  */
 
+import { isAbsolute, join } from "node:path";
 import { runAction } from "./lib/morning.js";
 import { authErrorKey } from "./lib/token.js";
 
@@ -43,6 +44,9 @@ type ExtCtx = {
     listExtState(e: string): Array<{ key: string; value: string }>;
   };
   getConfig(spaceId: string, key: string): string | null;
+  /** Structural subset of `AppConfig` — only what this extension reads. */
+  config: { spacesDir: string };
+  log: { warn(message: string, meta?: Record<string, unknown>): void };
 };
 
 /** Structural match for `MercuryExtensionAPI` (avoid package subpath imports). */
@@ -131,12 +135,20 @@ export default function (mercury: MercuryExt) {
     // from the env var rather than from stored state makes the dashboard
     // correct before the first token is ever minted.
     credentialEnvVar: CLIENT_ID_VAR,
-    // This connection can issue tax documents. In a group-linked space the
-    // runtime then requires explicit admin enablement
-    // (security.sensitive_connections_allowed) plus per-caller confirmation —
-    // see src/core/runtime.ts. That operational cost is intended; the README
-    // says so, because the symptom otherwise reads as a broken extension.
-    sensitive: true,
+    // NOT `sensitive: true`, despite issuing tax documents. The runtime's
+    // sensitive guard (src/core/runtime.ts:217) is host-global and
+    // space-blind: getActiveSensitiveConnectionName() scans every loaded
+    // extension, and checkSensitiveConnectionGuard never looks at the space or
+    // the prompt. One sensitive connection anywhere on the host therefore puts
+    // EVERY group-linked space behind a per-message confirmation — on a box
+    // with fourteen of them, thirteen unrelated spaces pay for this one. Worse,
+    // the confirmation does not stick: the pending entry is deleted on `yes`,
+    // so the next message asks again, forever.
+    //
+    // The load-bearing controls are elsewhere and unaffected: the credentials
+    // are hostOnly and brokered (rung 4), so they never enter a container, and
+    // mercury.permission({defaultRoles:["admin"]}) keeps the verbs admin-only.
+    // Restore this line when the guard scopes per-space or per-extension.
     // Side-effect free and fast, per the ConnectionDef contract (5s timeout):
     // it reports from stored state and never mints a token or makes a request.
     statusCheck: async (ctx) => {
@@ -167,6 +179,15 @@ export default function (mercury: MercuryExt) {
       spaceId: req.spaceId,
       callerId: req.callerId,
       environment: ctx.getConfig(req.spaceId, ENVIRONMENT_KEY),
+      // `expense-upload` reads a file the container named, so it needs the
+      // workspace root to confine that path to the caller's own space.
+      // `resolveProjectPath` is not an exported subpath of the package; this
+      // mirrors it (src/config.ts) rather than widening the package API for
+      // two lines. Keep the two in step.
+      spacesDir: isAbsolute(ctx.config.spacesDir)
+        ? ctx.config.spacesDir
+        : join(process.cwd(), ctx.config.spacesDir),
+      logDenial: (message, detail) => ctx.log.warn(message, detail),
     });
   });
 

package/examples/extensions/morning/lib/hosts.ts

@@ -15,6 +15,14 @@
  *     credential sets. A production key cannot mint against sandbox.
  *  3. Sandbox's API host is a `greeninvoice.co.il` name while its token host is
  *     a `morning.dev` name. They do not share a domain; do not "tidy" them.
+ *
+ * A fourth, added 2026-09-06 and verified the same way: `/file-upload/v1/url`
+ * carries PATH-LEVEL `servers` in the spec that override the global ones, so it
+ * is not reachable under `apiBase` at all — hence `uploadBase`. That makes three
+ * distinct sandbox hosts (`api.sandbox.morning.dev`,
+ * `sandbox.d.greeninvoice.co.il`, `api.sandbox.d.greeninvoice.co.il`) which read
+ * like typos of one another and are not. `tests/morning-extension.test.ts`
+ * asserts all six as literals so a tidy-up cannot collapse them.
  */
 
 export const MORNING_EXT = "morning" as const;
@@ -27,16 +35,24 @@ export interface MorningHosts {
   readonly tokenUrl: string;
   /** API base, no trailing slash. Every non-token call is `${apiBase}/<path>`. */
   readonly apiBase: string;
+  /**
+   * Base for the expense file-upload endpoint only, no trailing slash. A
+   * different origin from `apiBase` and without the `/api/v1` prefix — see the
+   * fourth note above.
+   */
+  readonly uploadBase: string;
 }
 
 const HOSTS: Record<MorningEnvironment, MorningHosts> = {
   production: {
     tokenUrl: "https://api.morning.co/idp/v1/oauth/token",
     apiBase: "https://api.greeninvoice.co.il/api/v1",
+    uploadBase: "https://api.morning.co",
   },
   sandbox: {
     tokenUrl: "https://api.sandbox.morning.dev/idp/v1/oauth/token",
     apiBase: "https://sandbox.d.greeninvoice.co.il/api/v1",
+    uploadBase: "https://api.sandbox.d.greeninvoice.co.il",
   },
 };
 

package/examples/extensions/morning/lib/morning.ts

@@ -29,6 +29,7 @@ import {
   mintIssueToken,
 } from "./issue-token.js";
 import { getAccessToken, recordAuthError, type TokenStore } from "./token.js";
+import { expenseUpload as runExpenseUpload } from "./upload.js";
 
 export interface CapabilityResult {
   status?: number;
@@ -43,6 +44,14 @@ export interface ActionContext {
   spaceId: string;
   callerId: string;
   fetchImpl?: typeof fetch;
+  /**
+   * Root of all space workspaces, project-resolved by the caller. Only
+   * `expense-upload` needs it; absent means that verb refuses rather than
+   * guessing a root.
+   */
+  spacesDir?: string;
+  /** Host-side WARN channel for refusals that must not be detailed to the caller. */
+  logDenial?: (message: string, detail: Record<string, unknown>) => void;
 }
 
 type Body = Record<string, unknown>;
@@ -439,6 +448,73 @@ async function documentSearch(ctx: ActionContext, body: Body) {
   });
 }
 
+async function expenseDraftSearch(ctx: ActionContext, body: Body) {
+  const { page, pageSize } = paging(body);
+  return apiCall(ctx, "POST", "/expenses/drafts/search", {
+    ...pick(body, [
+      "fromDate",
+      "toDate",
+      "description",
+      "supplierId",
+      "supplierName",
+    ]),
+    page,
+    pageSize,
+  });
+}
+
+/**
+ * Upload a receipt as an expense draft.
+ *
+ * Two hops to two different hosts, so it cannot be expressed as one `apiCall`.
+ * The token PROVIDER is handed over rather than a token: the retry policy lives
+ * in `upload.ts`, which is the only place that knows step 1 is safe to repeat
+ * and step 2 is not.
+ */
+async function expenseUpload(ctx: ActionContext, body: Body) {
+  if (!ctx.spacesDir) {
+    return {
+      status: 503,
+      data: {
+        error:
+          "expense-upload is unavailable: the host did not supply a workspace root.",
+      },
+    };
+  }
+
+  return runExpenseUpload(
+    {
+      env: ctx.env,
+      spaceId: ctx.spaceId,
+      spacesDir: ctx.spacesDir,
+      ...(ctx.fetchImpl ? { fetchImpl: ctx.fetchImpl } : {}),
+      ...(ctx.logDenial ? { logDenial: ctx.logDenial } : {}),
+    },
+    body,
+    {
+      async getToken(forceRefresh: boolean) {
+        const result = await getAccessToken(ctx.db, ctx.env, {
+          forceRefresh,
+          ...(ctx.fetchImpl ? { fetchImpl: ctx.fetchImpl } : {}),
+        });
+        if (result.ok) return { ok: true as const, token: result.accessToken };
+        if (result.kind === "auth_failed") {
+          recordAuthError(ctx.db, ctx.env, result.message);
+        }
+        return {
+          ok: false as const,
+          result: {
+            status: result.kind === "not_configured" ? 503 : 502,
+            data: { error: result.message, kind: result.kind },
+          },
+        };
+      },
+      recordAuthError: (message: string) =>
+        recordAuthError(ctx.db, ctx.env, message),
+    },
+  );
+}
+
 async function documentLinks(ctx: ActionContext, body: Body) {
   const id = typeof body.id === "string" ? body.id.trim() : "";
   if (!id) return usage("document-links requires an id");
@@ -462,6 +538,8 @@ const ACTIONS: Record<
   "document-create": documentCreate,
   "document-search": documentSearch,
   "document-links": documentLinks,
+  "expense-upload": expenseUpload,
+  "expense-draft-search": expenseDraftSearch,
 };
 
 export const AVAILABLE_ACTIONS = Object.keys(ACTIONS);