Merge origin/main into claude/issue-4405-filter-conformance-mongo

Author: claude

.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.

.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

.github/workflows/duplicate-fix-guard.yml

@@ -0,0 +1,140 @@
+# GitHub happily lets any number of open PRs declare `Fixes #N` for the same
+# issue. On 2026-08-02 that cost a full duplicate implementation: #4555 and
+# #4559 both declared `Fixes #4551`, both ran the whole gate suite green, and
+# the duplication sat machine-detectable from the moment the second PR opened
+# (03:08) until a human noticed it (08:52). All agents here share one GitHub
+# identity, so the issue's assignee could not warn the second author either —
+# "assigned to os-zhuang" reads the same whether it is you or another session.
+# Full post-mortem: #4588.
+#
+# This gate makes the second PR red at open time. First come, first served —
+# the EARLIER open PR (lower number) keeps its claim and stays green; the
+# later one fails with a pointer to it. That matches the pm-dispatch claim
+# convention ("first claim comment wins") already in .claude/skills/.
+#
+# Scope: same-repo references only (bare `#N` and qualified `<this repo>#N`).
+# Cross-repo references are the cross-repo-issue-closer's territory, and a
+# duplicate across repos cannot be resolved by failing one side's CI anyway.
+name: Duplicate Fix Guard
+
+# `edited` matters as much as `opened`: a PR that adds `Fixes #N` to its body
+# after the fact must re-run this check, and one that drops the line must be
+# able to go green again.
+on:
+  pull_request:
+    types: [opened, edited, reopened, synchronize]
+
+permissions:
+  pull-requests: read
+
+jobs:
+  duplicate-fix-guard:
+    name: No other open PR may claim the same issue
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check declared issues against other open PRs
+        uses: actions/github-script@v9
+        with:
+          script: |
+            const pr = context.payload.pull_request;
+            const thisRepo = `${context.repo.owner}/${context.repo.repo}`;
+
+            // GitHub's own closing-keyword set. The optional colon is part of
+            // GitHub's accepted syntax (`Fixes: #123`). Two same-repo forms:
+            // bare `#N` and qualified `owner/repo#N` naming THIS repo.
+            const KEYWORDS = 'close|closes|closed|fix|fixes|fixed|resolve|resolves|resolved';
+            const pattern = new RegExp(
+              `\\b(?:${KEYWORDS}):?\\s+(?:([\\w.-]+)\\/([\\w.-]+))?#(\\d+)\\b`,
+              'gi',
+            );
+
+            // Strip fenced blocks and inline code spans before matching.
+            // GitHub's own closing-keyword parser ignores code formatting, and
+            // this guard must not be stricter than the linker it protects:
+            // this very PR's first run counted its own DISCUSSION of
+            // `Fixes #4551` (in backticks, describing the incident) as a
+            // declaration. Benign there — #4551 is closed — but a prose
+            // mention of an issue some other open PR really fixes would have
+            // been a spurious red.
+            const declaredIssues = (body) => {
+              const prose = (body || '')
+                .replace(/```[\s\S]*?```/g, ' ')
+                .replace(/`[^`\n]*`/g, ' ');
+              const found = new Set();
+              for (const [, owner, repo, number] of prose.matchAll(pattern)) {
+                // A qualified reference to ANOTHER repo is not ours to judge.
+                if (owner && `${owner}/${repo}`.toLowerCase() !== thisRepo.toLowerCase()) continue;
+                found.add(Number(number));
+              }
+              return found;
+            };
+
+            const mine = declaredIssues(pr.body);
+            if (mine.size === 0) {
+              core.info('This PR declares no same-repo closing keywords — nothing to guard.');
+              return;
+            }
+            core.info(`This PR declares: ${[...mine].map((n) => `#${n}`).join(', ')}`);
+
+            // Branch-name convention (advisory, never red): a fix branch named
+            // `claude/issue-<n>-<slug>` is discoverable by the next session
+            // with one `git ls-remote | grep issue-<n>`. #4555 vs #4559
+            // happened partly because the branches shared no token to grep.
+            // Warning only — existing branches must not go red retroactively.
+            const branch = pr.head.ref;
+            if (![...mine].some((n) => branch.includes(`issue-${n}`))) {
+              core.warning(
+                `Branch \`${branch}\` does not name any declared issue. ` +
+                `Convention: claude/issue-<n>-<slug> (e.g. claude/issue-${[...mine][0]}-short-slug) ` +
+                `so parallel sessions can discover in-flight work with git ls-remote.`,
+              );
+            }
+
+            // Drafts count: a draft PR is work in flight, which is exactly
+            // what the second session needs to see.
+            const openPrs = await github.paginate(github.rest.pulls.list, {
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              state: 'open',
+              per_page: 100,
+            });
+
+            const conflicts = [];
+            for (const other of openPrs) {
+              if (other.number === pr.number) continue;
+              const theirs = declaredIssues(other.body);
+              const shared = [...mine].filter((n) => theirs.has(n));
+              if (shared.length > 0) conflicts.push({ other, shared });
+            }
+
+            if (conflicts.length === 0) {
+              core.info('No other open PR declares these issues.');
+              return;
+            }
+
+            // First come, first served: only the LATER PR goes red. Failing
+            // both would leave the original author red through no action of
+            // their own; failing the earlier one would reward racing.
+            const older = conflicts.filter((c) => c.other.number < pr.number);
+            const newer = conflicts.filter((c) => c.other.number > pr.number);
+
+            for (const { other, shared } of newer) {
+              core.info(
+                `#${other.number} (newer) also declares ${shared.map((n) => `#${n}`).join(', ')} — ` +
+                `it will fail its own run of this guard; this PR keeps its claim.`,
+              );
+            }
+
+            if (older.length > 0) {
+              const lines = older.map(({ other, shared }) =>
+                `  - ${shared.map((n) => `#${n}`).join(', ')} is already claimed by #${other.number} ` +
+                `(${other.html_url}, branch \`${other.head.ref}\`${other.draft ? ', draft' : ''})`,
+              );
+              core.setFailed(
+                `Another open PR already declares a fix for the same issue(s):\n${lines.join('\n')}\n` +
+                `If this PR is the duplicate, close it and add anything it uniquely covers to the ` +
+                `earlier PR or a follow-up issue (that is what saved #4560 when #4559 was closed). ` +
+                `If the EARLIER one is abandoned, close it first — this check re-runs on 'edited' ` +
+                `and 'synchronize', and goes green once the conflict is gone.`,
+              );
+            }