feat: integrate upstream runtime and dispatch updates by tiago-peixoto · Pull Request #19 · tiago-peixoto/firstmate

tiago-peixoto · 2026-08-18T21:45:52Z

Intent

Integrate official upstream into the permanent personal-fork main, as the captain ruled on 2026-08-18 and as tracked by firstmate-upstream-integration-2026-08-18. This is a scheduled upstream synchronization, not a feature change: the goal is that fork main carries every official upstream commit while still carrying every deliberate fork divergence, so live homes can keep consuming validated fork main by fast-forward.

It is also a hard precondition for separate work. The divergence integration for firstmate-declared-pause-not-absorbed is blocked behind it, because bin/fm-fork-topic.sh integrate refuses to add a divergence topic while official upstream is not integrated and validated into fork main.

What this candidate contains: fork main c88b1ff merged with upstream/main 03bb1d8, bringing the 8 upstream commits fork main lacked - remote secondmate delivery and state reporting (kunchenguid#2570), spendPriority quota dispatch (kunchenguid#2574), the GROK_BOT.md system prompt and its follow-ups (kunchenguid#2590, kunchenguid#2592), inactive reconciliation scan progress (kunchenguid#2595), and three documentation revisions. The merge was prepared through the owning helper in an isolated worktree of the private fork-integration clone, never in an operating checkout, and it resolved cleanly with no product conflicts, so no divergence re-justification decision was raised and no rerere resolution had to be settled.

Verification already performed before starting validation, per the fork-main-integration procedure:

The emitted git range-diff --remerge-diff review shows all 35 carried commits as identical; the only new entry is the merge commit itself, so the merge altered no divergence content.
The manifest health check validates against the candidate HEAD with errors=0, retained=4, and trend unchanged; all four pending divergences remain carried, and the merge touched three of them (firstmate-progressive-disclosure-restructure, fork-main-integration, supervision-owner-aware-recovery).
Spot checks confirm each touched divergence survived in the merged tree: the BASH_SUBSHELL lock-ownership guard that stock macOS Bash 3.2 requires is still present, the six fork integration helpers are still present, and the progressive-disclosure restructure is still present in AGENTS.md.
AGENTS.md auto-merged and was checked in both directions: all four lines upstream added since the previously merged point d023c45 are present in the merged result, and the fork's own restructure is intact. An earlier check of mine compared the wrong pair of refs and appeared to show upstream content missing; recomparing against the correct previously merged point showed nothing missing.

Acceptance for this change is that fork main ends up with official upstream as an ancestor while every deliberate divergence is still carried and the manifest stays healthy. Nothing here should alter product behaviour beyond what those upstream commits already carry, and no divergence may be silently dropped or weakened to make the merge succeed.

Constraints in force: never force-push or rewrite a published topic or pull-request branch; the delivery must go to fork main through this isolated fork-target registration rather than to official upstream; and the resulting fork pull request requires genuinely green fork CI and the captain's explicit merge approval using the regular merge method, so the inner topic merges stay reachable.

What Changed

Integrate official upstream through 03bb1d8 while preserving the fork’s tracked divergences and recording the synchronization in the manifest.
Make remote secondmate sends, peeks, and state reads reflect remote endpoint truth, and preserve inactive reconciliation progress under tight deadlines.
Move profile-array dispatch to quota-axi 0.1.29’s TOON-first spendPriority flow and add updated Grok, delegation, and secret-handling guidance.

Risk Assessment

⚠️ Medium: Captain, upstream ancestry and all carried fork commits are preserved, but the new cross-host read path can make fleet snapshots block for minutes when a remote worker is unhealthy or occupied.

Testing

After recreating the stripped remote-ref context in a disposable clone and enabling the quota suite’s explicit live mode, candidate health, the 35-commit range-diff, ancestry/content checks, six focused behavior suites, and manual remote-send/peek evidence all passed; this is a CLI/Git change with no UI screenshot applicable, and the worktree is clean.

Evidence: Candidate fork-health report

Fork divergence health: retained=4 patches=4 not-upstream=13 integration-artifacts=9 retired-history-patches=0 accepted-upstream-patches=0 trend=unchanged superseded=0 signals=9 errors=0
Refs: fork=HEAD@41a78196 upstream=upstream/main@03bb1d8b
Classes: pending=4 rejected-but-retained=0 private=0 superseded=0
Oldest pending: fork-main-integration introduced=2026-08-17 age_days=1
Last upstream merge touched: 3 (firstmate-progressive-disclosure-restructure,fork-main-integration,supervision-owner-aware-recovery)
fork-main-integration [pending] topic=fm/divergence/fork-main-integration upstream=open https://github.com/kunchenguid/firstmate/pull/1944
  does: Permanent fork-main integration workflow: guarded remote topology, isolated fork-target validation clone, divergence manifest and health report, topic integrate and discard helpers, upstream merge helper, and the startup upstream probe.
  retire when: Upstream pull request 1944 is merged into official upstream main, so official upstream ships the fork-main integration workflow itself.
supervision-owner-aware-recovery [pending] topic=fm/divergence/supervision-owner-aware-recovery upstream=open https://github.com/kunchenguid/firstmate/pull/2392
  does: Claude primary-session supervision fix: session-ownership alignment for the Stop auto-arm and turn-end guard, a bounded volatile entry trace, one-shot repeated-block escalation, a single supervision snapshot behind queue warnings, queued delivery treated as a supervision need until post-handling acknowledgement, and the BASH_SUBSHELL lock-ownership check stock macOS Bash 3.2 requires.
  retire when: Upstream pull request 2392 is merged into official upstream main, so official upstream ships owner-aware durable supervision recovery itself.
firstmate-brief-scaffold-trim-v2 [pending] topic=fm/divergence/firstmate-brief-scaffold-trim-v2 upstream=open https://github.com/kunchenguid/firstmate/pull/2538
  does: Trim generated brief scaffolds to retain only load-bearing worker instructions and current status protocol.
  retire when: upstream main carries this scaffold trim or an equivalent
firstmate-progressive-disclosure-restructure [pending] topic=fm/divergence/firstmate-progressive-disclosure-restructure upstream=open https://github.com/kunchenguid/firstmate/pull/2547
  does: Restructure Firstmate's always-loaded instructions toward progressive disclosure while preserving every operational rule and safety boundary.
  retire when: upstream main carries this restructure or an equivalent
Accepted upstream and retired: 0
Relevance review: git -C <isolated-candidate> range-diff --remerge-diff d023c451e00fb64f9845b27fa949c02beed8c551..c88b1ffbd0a01ea7b1c1646524977d2460aaf3ae 03bb1d8b78a8632ae2d9cea4c10868eb100e885e..HEAD
Manifest/Git signals (informational):
  - non-upstream commit fe30ee2e2ccf678bba877659e47bae71318a5fab is not represented by a canonical manifest topic
  - non-upstream commit 067881f8a67c9270edfb621784f7cf530fd38ccf is not represented by a canonical manifest topic
  - non-upstream commit 2def68de4882b16f3c5160dc44616a650606b321 is not represented by a canonical manifest topic
  - non-upstream commit d0a5f5a3f72a36e833b5ace9229d8bad8d1c407f is not represented by a canonical manifest topic
  - non-upstream commit 00e17f65aa3173ab9d3a3824565609baba569db6 is an integration-path artifact after cb61bd3364cdc8e2d0ef04fcad8096664bc1df60, not a carried divergence
  - non-upstream commit d51c7085780b106ec2b3b7d1847bf47e898889c6 is an integration-path artifact after 86df18c97a02421e3baf8003353476458293a208, not a carried divergence
  - non-upstream commit aee6c2e1eb55b8fca88d2d5cf216bc3e7bb28030 is an integration-path artifact after 3c9a985ad8763d92d9806284514a20b6af1ce5a0, not a carried divergence
  - non-upstream commit 5fd46854f7c3fc31027632d1fbd69bac06be6fea is an integration-path artifact after 1c3ae04d35b75e3c8293fa717855c997bcf77bac, not a carried divergence
  - non-upstream commit 1b15d8b7250eeb9b4ee37bc3c302e52231d1ec16 is an integration-path artifact after 1c3ae04d35b75e3c8293fa717855c997bcf77bac, not a carried divergence

Evidence: Carried-divergence range-diff

 1:  fe30ee2 =  1:  fe30ee2 fix(spawn): stop passing the removed --tui-mode flag on Pi launches (#2)
 2:  067881f =  2:  067881f feat(fork): sync upstream into live fork main (#3)
 3:  2def68d =  3:  2def68d fix(bin): make supervision recovery owner-aware and durable (#5)
 4:  d0a5f5a =  4:  d0a5f5a fix(bin): restore upstream ancestry and preserve wake status output (#7)
 5:  cb61bd3 =  5:  cb61bd3 Merge upstream/main into fork main
 6:  00e17f6 =  6:  00e17f6 no-mistakes(document): Document regular upstream merge requirement
 7:  18e95c7 =  7:  18e95c7 Merge pull request #8 from tiago-peixoto/fm/fork-upstream-ancestry-redo
 8:  86df18c =  8:  86df18c Merge upstream/main into fork main
 9:  d51c708 =  9:  d51c708 no-mistakes(document): Refresh upstream-sync documentation contracts
10:  1e24af6 = 10:  1e24af6 Merge pull request #9 from tiago-peixoto/fm/fork-upstream-sync-aug17
11:  3c9a985 = 11:  3c9a985 Merge upstream/main into fork main
12:  aee6c2e = 12:  aee6c2e no-mistakes(document): Document actionlint workflow coverage accurately
13:  fb41f2e = 13:  fb41f2e Merge pull request #10 from tiago-peixoto/fm/fork-upstream-sync-actionlint
14:  579c661 = 14:  579c661 Merge upstream/main into fork main
15:  09f4537 = 15:  09f4537 Merge pull request #11 from tiago-peixoto/fm/fork-upstream-sync-3
16:  33ec044 = 16:  33ec044 Merge upstream/main into fork main
17:  4efa5da = 17:  4efa5da Merge pull request #12 from tiago-peixoto/fm/fork-upstream-sync-4
18:  75441c6 = 18:  75441c6 Merge upstream/main into fork main
19:  39d18f2 = 19:  39d18f2 Merge pull request #13 from tiago-peixoto/fm/fork-upstream-sync-5
20:  06925cf = 20:  06925cf feat(fork): add permanent fork-main integration
21:  c4f48b2 = 21:  c4f48b2 Merge divergence fork-main-integration
22:  d257ba1 = 22:  d257ba1 fix(bin): make supervision recovery owner-aware and durable
23:  5ab8af3 = 23:  5ab8af3 Merge pull request #14 from tiago-peixoto/fm/reg-fork-machinery
24:  1c3ae04 = 24:  1c3ae04 Merge divergence supervision-owner-aware-recovery
25:  12e5d2a = 25:  12e5d2a Merge pull request #15 from tiago-peixoto/fm/reg-supervision-guard
26:  72715df = 26:  72715df Trim generated brief scaffolds
27:  957afe0 = 27:  957afe0 Merge divergence firstmate-brief-scaffold-trim-v2
28:  0abbc69 = 28:  0abbc69 Merge pull request #16 from tiago-peixoto/fm/fork-integrate-brief-scaffold-2538
29:  d6420c3 = 29:  d6420c3 Merge upstream/main into fork main
30:  2ab1d93 = 30:  2ab1d93 Merge pull request #17 from tiago-peixoto/fm/fork-upstream-sync-before-progressive-disclosure
31:  ba92ac4 = 31:  ba92ac4 docs: progressively disclose firstmate instructions
32:  232cc65 = 32:  232cc65 Merge divergence firstmate-progressive-disclosure-restructure
33:  5fd4685 = 33:  5fd4685 no-mistakes(document): Align Cursor unread-status supervision guidance
34:  1b15d8b = 34:  1b15d8b no-mistakes(lint): Restore submitted Cursor supervision guidance
35:  c88b1ff = 35:  c88b1ff Merge pull request #18 from tiago-peixoto/fm/fork-integrate-progressive-disclosure-2547
 -:  ------- > 36:  41a7819 Merge upstream/main into fork main

Evidence: Remote secondmate CLI transcript

$ bin/fm-send.sh rsm "please rename the metric"
fm-send: delivered to remote secondmate rsm; the remote pane accepted the text and Enter, and only the synchronous submit confirmation is still pending. This is not a failure - do not resend; the pending-reply expectation stays armed.
persisted expectation: phase=awaiting_report; delivered_epoch_recorded=yes
$ bin/fm-peek.sh rsm 20
● the remote mate is mid-refactor

Evidence: Integration acceptance facts

candidate=41a78196b191942570edc1a907b32ccfe10a6fe5
parents=c88b1ffbd0a01ea7b1c1646524977d2460aaf3ae 03bb1d8b78a8632ae2d9cea4c10868eb100e885e
official_upstream_ancestor=yes (03bb1d8b78a8632ae2d9cea4c10868eb100e885e)
incoming_official_commits=8
upstream_AGENTS_additions_present=4/4
GROK_BOT_matches_upstream_tip=yes
supervision_lock_guard=&& [ "${BASH_SUBSHELL:-0}" -eq 0 ]; then
fork_helpers_present=6 (five executables plus sourced fm-fork-lib.sh)

Evidence: Live spendPriority decisions

Higher spendPriority case: SELECTED=codex
Unknown quota case: DECISION=CODEX
Required reasoning class case: SELECTED=claude
Insufficient runway case: SELECTED=codex

Pipeline

Updates from git push no-mistakes

✅ **intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

⚠️ **Review** - 1 warning

⚠️ bin/fm-crew-state.sh:163 - The new remote state read has no local deadline. A busy or wedged remote worker can leave fm-on.sh waiting for minutes; fm-fleet-snapshot.sh calls this helper before its existing 8-second remote probe, defeating its invariant that one broken home cannot hang the snapshot. Bound remote reads with the shared timeout mechanism, propagate the snapshot timeout, and apply the same contract to fm-peek.sh remote capture.

✅ **Test** - passed

✅ No issues found.

git show --no-patch --format=... 41a78196b191942570edc1a907b32ccfe10a6fe5 and git log --reverse c88b1ff..03bb1d8
bin/fm-fork-status.sh --repo "$PWD" --fork-ref HEAD --facts-only (initial setup lacked the stripped upstream remote), then candidate health in a disposable clone with reconstructed canonical refs
git range-diff --remerge-diff d023c451..c88b1ff 03bb1d8..HEAD
tests/fm-send-remote-delivery.test.sh
tests/fm-peek-remote.test.sh
tests/fm-crew-state.test.sh
tests/fm-inactive-reconcile.test.sh
tests/fm-quota-array-dispatch-live-e2e.test.sh (default skip), then FM_QUOTA_ARRAY_DISPATCH_LIVE_E2E=1 tests/fm-quota-array-dispatch-live-e2e.test.sh
tests/fm-fork-main.test.sh
Manual bin/fm-send.sh delivery, persisted pending-reply inspection, and bin/fm-peek.sh against a deterministic remote transport fixture
Direct ancestry/content checks for merge parents, eight upstream commits, four upstream AGENTS.md additions, GROK_BOT.md, the Bash 3.2 guard, and six fork helpers
Final evidence integrity, upstream ancestry, transient-file cleanup, and git status --porcelain=v1 verification

✅ **Document** - passed

✅ No issues found.

✅ **Lint** - passed

✅ No issues found.

✅ **Push** - passed

✅ No issues found.

…chenguid#2570) * fix(bin): report remote secondmate delivery and state truthfully A steer to a remote secondmate crosses fm-on.sh to a host-local fm-send leg whose unconfirmed submit read-back (verdict=pending, typically a busy mate whose harness queues the steer) was flattened into exit 1, so the parent printed "error: text not submitted" / "error: text not sent" and discarded the pending-reply expectation for a steer that had actually landed. fm-send now carries the verdict across the ssh boundary as a documented delivered-unconfirmed exit 3: the parent reports the steer as delivered with confirmation pending, exits 0, keeps the expectation armed (awaiting_report), and closes --resolve-key decisions, while transport loss (ssh 255) and real remote failures keep failing loudly with the remote leg's stderr attached. A local unconfirmed submit now also exits 3 with an honest non-error message and still never closes a decision key. fm-crew-state.sh and fm-peek.sh no longer read a remote mate's endpoint through local probes (which misreported a healthy mate as "worktree gone" / "can't find session: remote"): both now use the true remote source over fm-on.sh, and an unreachable or unreadable remote reads as unknown-remote, never as gone or dead. * no-mistakes(document): Document remote delivery and state truth * no-mistakes: apply CI fixes

* Adopt quota-axi 0.1.29 spendPriority-primary array dispatch. quota-axi 0.1.29 publishes schema 5 with selection.spendPriority as the primary comparative signal and demotes derivation fields out of default --json. Rank comparable-fit candidates on that scalar, keep runway versus the completion horizon as a hard gate, and raise the compatibility floor so a pre-consolidation build cannot reach dispatch intake. * no-mistakes(review): Correct schema fixtures and remove prescriptive selection prompts * no-mistakes(document): Correct quota verification evidence chronology * Collapse quota-array-dispatch onto TOON-first spendPriority ranking. Decide from quota-axi's default TOON; keep --json as a rare defensive fallback. Rank by spendPriority after eligibility, reasoning-class, and runway-feasibility gates, and drop the hand-computed Pareto, pace, reserve, and window-id layers. * no-mistakes(review): Permit ambiguous JSON fallback and correct reset fixtures * no-mistakes(review): Correct runway semantics and escalate unresolved uncertainty * no-mistakes(document): Document TOON-first quota dispatch evidence

* docs: add GROK_BOT.md Grok Bot system prompt * docs: amend GROK_BOT.md with charter report-back and delegation marker * docs: classify GROK_BOT.md as public-product * docs: make GROK_BOT.md the plain Grok Bot system prompt

…guid#2592)

Refine language for clarity and consistency in instructions.

…#2595) * fix(bin): guarantee inactive-reconcile scan progress under second quantization The inactive-outcome scan computed its aggregate deadline in whole seconds, so a 1-second budget's effective value lands anywhere in (0,1]; a scan starting just before a wall-clock second boundary rounded its whole budget away mid-scan and exited having visited no child, while the durable cursor had already advanced past the never-examined child. This is the CI flake behind tests/fm-inactive-reconcile.test.sh's 'next bounded scan did not resume with the following child' (watcher-wake-lock family, portable serial 2, seen on the PR kunchenguid#2590 run). Every scan now visits at least its first due child with the per-child state-read bound floored at one second, so no invocation can be a zero-work no-op. The outer process-group kill moves to budget+1s: the scan's own deadline enforces the budget, and the kill is a backstop for a scan wedged in an unbounded wait instead of a racer that routinely preempts the clean bounded exit. The wake-lock-wait test bound tracks the backstop (3s -> 4s); the previously flaky assertion is unchanged. * no-mistakes(document): Document inactive-reconcile deadline backstop

Refactor the guidelines for Firstmate's role and delegation process, emphasizing the importance of crewmates and asynchronous work.

Clarified guidelines for handing off work to crewmates and managing secrets.

kunchenguid and others added 10 commits August 18, 2026 00:05

docs: update GROK_BOT.md nautical terms and self-improvement (kunchen…

9d2ad81

…guid#2592)

doc: Update language in GROK_BOT.md for clarity

f758e51

Refine language for clarity and consistency in instructions.

doc: Revise Firstmate delegation and communication guidelines

63362d2

Refactor the guidelines for Firstmate's role and delegation process, emphasizing the importance of crewmates and asynchronous work.

doc: Update work delegation and secret management instructions

03bb1d8

Clarified guidelines for handing off work to crewmates and managing secrets.

Merge upstream/main into fork main

41a7819

no-mistakes(document): Document Grok prompt ownership and formatting

d852238

tiago-peixoto merged commit 1ee9557 into main Aug 19, 2026
13 checks passed

tiago-peixoto deleted the fm/fork-upstream-integration-2026-08-18 branch September 4, 2026 21:11

Navigation Menu

feat: integrate upstream runtime and dispatch updates - #19

feat: integrate upstream runtime and dispatch updates#19
tiago-peixoto merged 10 commits into
mainfrom
fm/fork-upstream-integration-2026-08-18

tiago-peixoto commented Aug 18, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

tiago-peixoto commented Aug 18, 2026

Intent

What Changed

Risk Assessment

Testing

Pipeline

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants