Merge remote-tracking branch 'origin/main' into claude/issue-4587-metadata-event-dual-source

Author: claude

.changeset/adr-anchors-authz-sweep.md

@@ -0,0 +1,18 @@
+---
+---
+
+Tooling-only: expand `scripts/adr-anchors.json` from 8 to 15 anchors — the bounded authz/security ADR sweep promised in #4575. Releases nothing.
+
+The first 8 anchors covered only #3723's blast radius. This sweep audited the decisions in ADR-0057 / 0066 / 0068 / 0090 / 0091 / 0095 / 0105 for other load-bearing realizations — places where a reasonable engineer could "fix" the code and be reverting a decision. Seven files added, each with its reversal story:
+
+- `posture-ladder.ts` (0095) — posture derives from capability grants; re-reading the better-auth role reopens the #2836 dual-track class.
+- `grant-validity.ts` (0091) — window enforcement lives at resolution time; "optimize it into a cleanup job" is the banned move (ADR-0049).
+- `tenant-layer.ts` (0095 D1) — Layer 0 shares no compiler/merge/bypass with business RLS; "deduplicate into the RLS compiler" would let a Layer-1 change weaken tenant isolation.
+- `auto-org-admin-grant.ts` (0105) — wall-less postures get `organization_admin_no_bypass`; "why two sets?" collapses into an environment-wide superuser (the F2 finding).
+- `invitation-placement.ts` (0105 D8) — issuance dry-runs the gate; "acceptance re-checks anyway" is false (acceptance runs under system context) and skipping it is an escalation hole.
+- `position.zod.ts` (0090 D3) — positions are flat; adding `parent` is the exact mistake ADR-0057 D5 retired.
+- `permission-evaluator.ts` (0066 D2 + 0057 D1) — superuser bypass derives from the wildcard grant, no stored boolean and no role fast-path.
+
+Plus one extension: the existing `resolve-authz-context.ts` anchor gains ADR-0068 (`platform_admin` is derived from an unscoped grant — no trusted stored boolean, the classic "add an `is_admin` column" reversal target).
+
+All 15 pass as-is — every anchored file already cited its governing ADRs — so this changes zero code, only registers what must not be silently un-cited. Negative-tested by stripping `ADR-0091` from `grant-validity.ts` (fails, printing the invariant).

.changeset/adr-anchors-guard.md

@@ -0,0 +1,6 @@
+---
+---
+
+Tooling-only: `pnpm check:adr-anchors` — code an accepted ADR governs must keep naming it (#3723 follow-up). Adds `scripts/check-adr-anchors.mjs` + `scripts/adr-anchors.json` (8 seeded anchors, all in the blast radius of the incident), a `Lint & Type Check` step, and Prime Directive #13 in `AGENTS.md` ("an accepted ADR binds until a superseding ADR says otherwise"). Releases nothing — no package changes.
+
+The incident this closes: three accepted ADRs said `sys_member.role` must never carry RBAC authority, and a patch-level changeset made app-declared names storable there anyway; a follow-up then made it automatic in every host. The mechanism was not carelessness — the file being edited never named the ADRs that governed it, so the author could not have known. The check is a presence check (does the governed file still reference its ADR ids?), deliberately dumb; the value is that the failure carries the **invariant**, not just an id to paste back, and it fires on exactly the diff that warrants a second look — someone rewriting a governed block and dropping the rationale with it.

.changeset/declarative-cron-job-schedule-envelope.md

@@ -0,0 +1,38 @@
+---
+"@objectstack/runtime": patch
+"@objectstack/observability": patch
+---
+
+fix(runtime): declarative `defineJob` cron jobs are actually scheduled (#4567)
+
+Every background job authored as `defineJob({ schedule: { type: 'cron', … } })`
+was **silently never scheduled**. `JobSchema.parse` rewrites the cron
+`expression` into the canonical expression envelope
+(`{ dialect: 'cron', source: '0 1 * * *' }` — the authoring/persistence tier),
+but `AppPlugin` handed `job.schedule` verbatim to `IJobService.schedule`, whose
+boundary contract documents `expression` as a **bare cron string** because
+`CronJobAdapter` passes it straight to croner. croner rejected the object
+(`CronPattern: Pattern has to be of type string.`), the throw was swallowed by a
+per-job `try/catch` that only `warn`ed, and the author saw a green build and a
+green boot with the job never running. `interval` / `once` schedules and
+flow `schedule` triggers were unaffected.
+
+**Fix (contract-first).** The authoring→boundary downgrade now happens at the one
+place the two tiers meet — `AppPlugin`'s declarative-job registration, alongside
+the existing `retryPolicy` / `timeout` threading — via
+`toBoundaryJobSchedule()`. The adapters stay strict: no `typeof === 'object'`
+tolerance was added downstream, so the boundary keeps exactly one shape.
+A schedule that cannot be reduced to it (unknown type, AST-only or non-`cron`
+expression envelope, missing `intervalMs` / `at`) is rejected by name.
+
+**The failure path is no longer silent.** A job that cannot be scheduled now logs
+at **error** level with its own message (`Background job FAILED TO SCHEDULE — it
+will never run`), plus a boot summary line when any job failed, and increments
+the new `job_schedule_failures_total` counter
+(`SEMCONV.jobScheduleFailuresTotal`, labels `app` / `job`) on the observability
+metrics registry. "Failed to schedule" no longer shares the quiet `warn` used by
+"handler not found in bundle.functions" — the first is an outage of declared
+work, the second is a job that was never going to run.
+
+No authoring change is required: existing `defineJob` cron declarations start
+working on upgrade.

.changeset/duplicate-fix-guard.md

@@ -0,0 +1,32 @@
+---
+---
+
+ci: fail a PR at open time when an earlier open PR already declares a fix for
+the same issue (#4588)
+
+Release-nothing: adds `.github/workflows/duplicate-fix-guard.yml` and updates
+agent process docs (AGENTS.md, CLAUDE.md, pm-dispatch claim template) — no
+package code.
+
+GitHub lets any number of open PRs declare `Fixes #N` for the same issue.
+On 2026-08-02, #4555 and #4559 both declared `Fixes #4551` and both were
+implemented in full — 834 duplicate lines through the whole gate suite — with
+the duplication machine-detectable from the second PR's open (03:08) yet
+unnoticed by any human until 08:52. The shared GitHub identity made the
+issue's assignee useless as a warning: "assigned to os-zhuang" reads the same
+whether the claimant is you or another session.
+
+Three changes, one per hole:
+
+- **Duplicate Fix Guard workflow**: on PR opened/edited/reopened/synchronize,
+  parse same-repo closing keywords and fail the PR if an EARLIER open PR
+  (lower number) declares the same issue, naming it. First come, first
+  served — matching the pm-dispatch "first claim comment wins" convention.
+  The check is body-driven and re-runs on `edited`, so a red PR goes green
+  the moment the conflict is resolved either way.
+- **Claim comments must carry a session ID** (pm-dispatch template, AGENTS.md,
+  CLAUDE.md): under a shared identity, the comment's session line is the only
+  thing that makes "is this claim mine?" answerable.
+- **Branch naming `claude/issue-<n>-<slug>`** (AGENTS.md): puts the issue
+  number where `git ls-remote | grep issue-<n>` can find it; the workflow
+  warns (never fails) when a fix PR's branch names no declared issue.

.changeset/pm-dispatch-escalation-bar.md

@@ -0,0 +1,4 @@
+---
+---
+
+Internal agent tooling only (`.claude/` pm-dispatch escalation bar + API-body generics trap) — releases nothing.

.changeset/save-flow-canonicalization-fallback-warning.md

@@ -0,0 +1,35 @@
+---
+"@objectstack/metadata-protocol": patch
+---
+
+fix(metadata-protocol): a flow save that skipped canonicalization says so (#4580)
+
+`saveMetaItem` canonicalizes flow bodies before the schema gate (#4542). When the
+canonicalizer throws — it is stricter than the gate: strict parse, cycle
+detection, control-flow region validation — the save falls back to the raw body
+so a work-in-progress draft with a temporary cycle stays saveable. That fallback
+is correct and unchanged. It was also completely silent.
+
+Of the four postures at this seam, three announce themselves: a clean
+canonicalization heals the row, a refused rename fails with `409
+FLOW_CONVERSION_CONFLICT` naming the token, and a host with no automation service
+is reported by `os migrate meta --stored`. The throw-fallback said nothing, so a
+save that skipped canonicalization was indistinguishable from one that healed the
+row — and a body that is *both* a legacy dialect and unparseable by the strict
+canonicalizer re-persisted verbatim. That is the exact #4542 symptom, arriving
+silently, while the boot warning for legacy stored rows tells the author that
+re-saving is the remedy.
+
+The fallback now emits a `console.warn` naming the flow and the canonicalizer's
+own error, deduped once per flow per process (the `convertStoredItem` pattern —
+Studio autosaves the same draft repeatedly, and a WIP cycle throws on every
+write). This aligns the write seam with ADR-0087 D2's "loud" posture, where
+conversions emit notices, reads warn once per row, and `migrateStoredMetadata`
+reports `failed` with the message.
+
+No behavior change: the body still saves, the schema gate stays the arbiter, and
+`registerFlow` still refuses to arm a malformed flow. Refusing the save in
+publish mode was considered and rejected — publish is the default mode, so it
+would silently tighten validation for every existing caller, and it could only be
+enforced on hosts that have an automation service, making the same body saveable
+on a control-plane host and a 422 on an automation host.

.claude/agents/os-dev.md

@@ -33,6 +33,23 @@ rules that most often get missed:
    consumer (`??` alias, tolerant parse), the bug is at the producer or in the
    spec — fix it there, or return `needs_decision`.
 
+**Resource discipline — parallel agents share ONE container; unbounded
+build/test runs OOM it.** Binding rules:
+
+1. **Serialize the heavy phase.** Wrap every build and test run in the shared
+   verification lock, so editing parallelizes but memory peaks never stack:
+   `flock -w 7200 /tmp/os-heavy-verify.lock -c '<build/test command>'`
+   (one lock file per container; waiting on it is normal, not a hang).
+2. **Cap the heap.** Prefix heavy commands with
+   `NODE_OPTIONS=--max-old-space-size=4096` (raise only with a reason).
+3. **Scope, don't sweep.** Build and test the affected packages
+   (`pnpm --filter <pkg> build/test`), not the whole repo, unless the task
+   explicitly requires a full pass. Cap test parallelism:
+   vitest `--maxWorkers=2`, turbo `--concurrency=2`.
+4. **Clean up when done**: after the PR is up, remove your worktree
+   (`git worktree remove <path> --force`) — leftover `node_modules` trees
+   exhaust the container's disk, which fails as confusingly as OOM.
+
 Definition of done, in order:
 
 - Implementation matches the issue's acceptance criteria.
@@ -89,3 +106,10 @@ Final message — exactly this JSON, no prose around it:
 
 Use `status: "rework"` for a partial result you know is incomplete (say why in
 `summary`); the PM will review and re-dispatch with feedback.
+
+Practical trap when filing issues/PRs through the GitHub API: the body
+sanitizer strips `<` followed by a letter as an HTML tag **at rest**, which
+destroys TypeScript generics (`Assert<Equal<1, 2>>` is stored as `Assert>`).
+Write generics with a space after each `<` — `Assert< Equal< 1, 2 > >` is
+still valid TypeScript — and read the stored body back to verify when a
+snippet is load-bearing.

.claude/skills/pm-dispatch/SKILL.md

@@ -102,7 +102,23 @@ known case: accepting a `repo:objectui` PR ⇒ file a `pm:queue` issue in
 `objectstack` — "run `pnpm objectui:refresh` and land the console bump",
 referencing the merged PR, blocked-by it until it actually merges.
 
-**4. One board, no second tracker.** The pm labels above are the state
+**4. Multiple PM sessions shard by repo — never share one queue.** The
+claim protocol makes concurrent PMs *safe*, not *useful*: batch
+independence (file-disjointness) is only checked within one PM's view, so
+two PMs on the same queue can claim different issues that collide on
+shared files, and the merge queue is one lane regardless. Scaling order:
+
+1. One PM, bigger batch (`batch:5` is the maintainer's chosen operating
+   point, riding on the resource discipline above), heavy tasks via
+   `mode:cloud` — adds compute without adding schedulers.
+2. When one PM genuinely can't keep up: a second session takes a **whole
+   repo** as its shard (`/pm-dispatch repo:objectstack-ai/objectui`) —
+   file universes are disjoint by construction. A sharded PM states its
+   shard in every claim comment and **never claims outside it**; cross-repo
+   parent/sub-issue chains stay with the main-backlog PM.
+3. Multiple PMs on the SAME queue: prohibited — all cost, no throughput.
+
+**5. One board, no second tracker.** The pm labels above are the state
 machine; an org-level GitHub Project pulling issues/PRs from all three repos
 gives the maintainer a single view (filter by `repo:*` and `pm:*`). The PM
 maintains no tracking state outside GitHub — that invariant is what keeps
@@ -189,18 +205,34 @@ execute atomically, in order:
 1. **Assign** to yourself (`@me`) and add `pm:dispatched`. Skip — and drop
    from the batch — any issue that acquired an assignee since step 1.
 2. **Claim comment** (Chinese), fixed shape — the branch name is the key,
-   every later artifact (worktree, push, PR) hangs off it:
+   every later artifact (worktree, push, PR) hangs off it. The session ID is
+   NOT optional: under the shared identity it is the only line that lets a
+   later reader — including your own future self after a context reset —
+   answer "is this claim mine?". A claim without it caused the #4555/#4559
+   duplicate (#4588): the second session saw its own shared name as assignee
+   and could not tell the claim was someone else's.
    > 认领:PM 循环第 N 轮
+   > 会话:`session_<id>`
    > 分支:`claude/issue-<n>-<slug>`
    > Worktree:`<repo>-issue-<n>`
 3. **Race check**: assignment is idempotent, so two agents can both
    "succeed". Re-read the comments; if an earlier claim comment with a
-   *different* branch name exists, you lost — touch nothing of theirs,
-   reply 「已有认领,让行」, and pick another issue. First comment wins.
+   *different* session ID or branch name exists, you lost — touch nothing of
+   theirs, reply 「已有认领,让行」, and pick another issue. First comment wins.
 
 Dev agents push their branch early — a remote branch is the hardest evidence
 of work in flight, closing the gap between "claimed" and "PR exists".
 
+**Multiple GitHub accounts (colleagues' Claude Code sessions) simplify
+this, not complicate it.** Across accounts the assignee alone already says
+*who*: `assignee isn't you → taken, never touch` is the entire cross-account
+protocol, and it's already the rule. The claim-comment ritual (branch name,
+round, race check) matters *within* one account's sessions. When several
+accounts work the backlog, partition it the same way as multi-PM sharding —
+by repo or by an agreed label per account — and record the assignment table
+once in a pinned issue or the round report so nobody triages another
+account's shard.
+
 **Stale-claim reclaim**: a claim older than ~24 h whose promised branch does
 not exist on the remote and has no PR is presumed dead — comment asking, and
 after another window of silence, remove the assignee (note why) and return
@@ -242,6 +274,19 @@ Follow your operating procedure (you are the os-dev agent). Non-negotiables:
 Return ONLY the JSON report defined in your agent definition.
 ```
 
+#### Resource limits — parallel agents share ONE container
+
+Memory peaks come from **build + test**, not editing, so the fix is not less
+parallelism but serialized heavy phases: the os-dev definition requires every
+build/test run to hold the container-wide verification lock
+(`flock /tmp/os-heavy-verify.lock`), a `NODE_OPTIONS=--max-old-space-size`
+heap cap, scoped `--filter` builds/tests, capped vitest/turbo workers, and
+worktree cleanup after the PR is up. PM-side: treat `batch:3` as assuming
+normal-sized tasks — for build-heavy ones (dependency-family upgrades, full
+regression passes) drop to `batch:2`, or dispatch that issue via
+`mode:cloud` so it gets its own container. If an agent dies with a
+heap/OOM signature, redispatch it alone rather than into a full batch.
+
 #### Dispatch backends
 
 **`mode:subagent` (default).** The `Agent` tool, as described above. The devs
@@ -313,8 +358,36 @@ Verdict per issue:
 
 ### 8. Escalate uncertainties to the maintainer
 
-Whenever a dev returns `needs_decision`, an issue is too vague to dispatch, or
-rework has failed twice:
+**First, apply the escalation bar — most things that FEEL like decisions are
+not.** The maintainer's words: 「明显的问题直接修,不是事事都需要我确认」.
+Escalate ONLY when at least one of these holds:
+
+- the options genuinely diverge on **product semantics or public contract
+  shape** and neither the issue, AGENTS.md, ADRs, nor existing code norms
+  determines the answer;
+- the fix requires a **destructive or hard-to-reverse action** (stored-data
+  migration shape, deleting a shipped capability, force operations).
+
+Everything else is the PM's call — decide, dispatch, and give the maintainer
+a **veto window instead of a permission gate**: state what you decided and
+why in the issue comment and the round report; they can stop it, but you do
+not wait for them. Named non-escalation classes (act immediately):
+
+- **Restore-invariant fixes.** When the repo already states the invariant —
+  one contract version across the family, declared = enforced, a gate must
+  actually compile/run what it claims to check — a finding that the
+  invariant is broken carries its own decision. A dual-version dependency
+  graph, an inert tripwire, an unwired gate: queue it, dispatch it, report
+  it. Asking "may I restore the invariant?" is the anti-pattern.
+- **Sequencing and dependency ordering** between technical tasks.
+- **Verification strategy** (what regression pass a risky-but-decided change
+  needs) — that is scoping the work, not deciding it.
+- A dev's `needs_decision` that, on PM review, falls into the classes above:
+  answer the dev yourself with the decision and rationale; do not relay it
+  upward.
+
+Whenever a dev returns `needs_decision` that passes the bar above, an issue
+is too vague to dispatch, or rework has failed twice:
 
 1. **Default: the decision lives ON the issue it belongs to — never a new
    issue.** Post the analysis as a comment on that issue, add the