feat(bin): support named crew and integration branches by lakshyads05 · Pull Request #6251 · kunchenguid/firstmate

lakshyads05 · 2026-09-30T18:51:08Z

Intent

Captain explicitly requests fixing the current conflict and all current Greptile findings on #6251. Do not merge.

Current forge reality: the PR targets main, head is 6ccc9af8665ce7850c8da78ea2fa751a2c4f8f53, and it is CONFLICTING/DIRTY with main.

Use the supported no-mistakes custody/rebase flow to bring this PR up to current upstream main and resolve the conflict. Preserve the named-branch implementation and all uncommitted work; never force-discard by inference.
Inspect and fix every current Greptile comment, including the new P2 finding that an ordinary completed-task body line such as local office is being mistaken for a landing note when no local merge occurred. Keep genuine local-only landing evidence while rejecting ordinary prose.
Re-run the focused regression suites and the full required validation flow after the conflict resolution and fixes. Update the PR with the new validated head and report the checks. Do not waive checks, add a trigger commit, merge, or perform unrelated cleanup.

What Changed

Added explicit full crew-branch and integration-branch selection across brief generation, spawning, promotion, review, teardown, and local landing workflows, including bare repositories.
Hardened branch reservations, base refreshes, locking, and linked-worktree safety for named branches and shared project origins.
Marked and constrained local-only landing notes so fleet snapshots preserve genuine landing evidence without treating ordinary completion prose as a landing note, with expanded regression coverage and documentation.

Risk Assessment

⚠️ Medium: The change is broad across lifecycle locking, named branches, integration bases, promotion, teardown, and landing-note projection, but the reviewed paths contain no substantiated source defect or intent contradiction.

Testing

Validated named branch lifecycle, adversarial local-note projection, and backlog/session replay. No linters, formatters, or full repository suite were run.

Live validation: ✅ go - 3 of 3 scenarios driven live against the product

Scenario	Result	Live	Evidence
Named branch selection, spawn guards, promotion, review, local landing, bare repositories, and origin reservations pass.	✅ pass	live	`bash tests/fm-named-branches.test.sh`
Marked local landing evidence survives captain resolution while ordinary prose is rejected.	✅ pass	live	fleet-snapshot-view.log
Named local completion notes survive session-start backlog replay.	✅ pass	live	backlog-atomicity.log

Evidence: Fleet snapshot validation

Source: Fleet snapshot validation

ok - empty fleet snapshot and view use explicit absence markers
ok - fixture snapshot covers task rows, backlog rows, pointers, stable ordering, and emission-time event age
ok - home-summary excludes kind=secondmate from unowned_current and terminal_in_flight
ok - undated captain holds age after a configurable threshold, decided only from structured fields
ok - captain-hold buckets are total, mutually exclusive, and never decided by prose
ok - main_inventory discloses orphan/unstructured and clears when inventory is consistent
ok - backlog normalization preserves strict roles and resolves every blocker compatibly
ok - snapshot event hints follow reconciled current state
ok - durable fold keeps an open decision past a later unrelated event
ok - a live secondmate endpoint preserves unrelated open decisions
ok - durable captain-held transfer closes the duplicate live status decision
ok - durable fold clears a decision only on a keyed resolution
ok - a completed scout's stale decision surfaces as a report pointer, not pending
ok - a scout still parked at a decision stays pending (terminal clear does not over-fire)
ok - snapshot includes durable scout reports after teardown
ok - snapshot parses tasks-axi rows and respects operational overrides
ok - fleet view renders the snapshot without secondmate peek guidance
ok - fleet view renders secondmate agent liveness

Evidence: Backlog atomicity validation

Source: Backlog atomicity validation

ok - backend resolution preserves unreadable configuration errors for every caller
ok - backend resolution preserves environment, project, user, and default precedence
ok - backlog readers and mutations refuse unresolved backends without touching either backlog
ok - captain hold refuses backend errors and preserves relocated addressing for valid configuration
ok - dispatch publishes the record and moves the backlog item In flight in one run
ok - dispatch omits the markdown file when probing a Beads backlog
ok - a leftover markdown symlink does not brick a Beads home's dispatch
ok - completion applies and closes a Beads backlog without any markdown file
ok - dispatch refuses to supersede a pending authoritative close
ok - dispatch refuses held rows before creating resources
ok - dispatch refuses dependency-blocked rows before creating resources
ok - dispatch refuses held In-flight rows before relaunch
ok - dispatch reads backlog rows from the backlog addressing root
ok - recovery uses the parent of a trailing-slash data record
ok - completion targets nested relative data from the caller directory
ok - an immediate-child absolute data path keeps one paired backlog
ok - bare relative data addresses one backlog through dispatch and completion
ok - dispatch refuses symlinked backlogs without crossing homes
ok - automatic homes refuse lifecycle mutation without compatible tasks-axi
ok - dispatch refuses an unresolvable backlog data directory
ok - completion refuses before mutation when backlog data is unresolvable
ok - dispatch refuses, before creating anything, when the home has no item for the id
ok - dispatch distinguishes backlog read failures from missing items
ok - dispatch refuses a closed item instead of silently reopening it
ok - dispatch cannot commit without a verified task-record publication
ok - a failed backlog transition fails the dispatch loudly and leaves no record
ok - dispatch reports when failed-transition rollback cannot remove its record
ok - dispatch verifies both task and busy records during rollback
ok - dispatch commits neither record nor backlog state before launch delivery succeeds
ok - dispatch retries interrupted transitions before honoring termination
ok - a signal-deferred spawn verifies its preserved state and repairs a row that did not move
ok - a signal-deferred spawn reports attempted preservation as attempted when it cannot be verified
ok - a signal-deferred spawn bounds its verification so an unresponsive tasks-axi cannot hold the meta lock forever
ok - fm_tasks_axi bounds the call through its perl watchdog when no timeout binary exists
ok - fm_tasks_axi's perl watchdog passes the child status and output through unchanged
ok - fm_tasks_axi fails closed rather than running unbounded when no bounding mechanism exists
ok - fm_tasks_axi's GNU timeout kills a child that ignores SIGTERM after one further bound
ok - Kimi readiness interruptions fail before backlog commit
ok - dispatch does not resurrect a row closed after preflight
ok - dispatch fails when its backlog row vanishes after preflight
ok - completion closes a local-only ship, with its landing note, before reporting success
ok - completion records the repository's non-main default landing branch
ok - completion closes a scout item against its report
ok - completion leaves legacy records open when no incarnation can be recorded
ok - completion refuses ambiguous task incarnations
ok - completion records relocated scout reports relative to the backlog root
ok - space-containing scout report paths round-trip through recovery
ok - control-byte data paths fail closed before paired transitions
ok - unreplayable data paths are refused before destructive cleanup
ok - completion preserves recovery state when task-record removal fails
ok - completion refuses to report success while its item is still open, and records what it owes
ok - restart recovers closes recorded before destructive cleanup
ok - completion refuses directory-symlink close targets
ok - completion reports failure until its durable close marker is removed
ok - session start retries a close whose marker could not be removed
ok - session start reports owned backlog rows it cannot read
ok - Orca cleanup recovery is excluded from backlog lifecycle transitions
ok - session start marks an item In flight when this home already owns a worker for it
ok - session start rejects internal worker-record symlinks
ok - session start rejects symlinked worker records
ok - session start finishes a close an interrupted cleanup recorded but never landed
ok - session start replays a recorded Gerrit close with its change URL as a note
ok - session start preserves a named local landing note
ok - recovery backfills recorded links onto already Done items
ok - session start preserves a pending close across a transient backlog read failure
ok - recovery preserves incomplete-cleanup evidence across a failed replay
ok - session start finishes a close for the matching meta incarnation
ok - recovery preserves closes for ambiguous task incarnations
ok - recovery preserves both records when meta removal fails
ok - recovery preserves closes beside symlinked metadata
ok - recovery binds close-marker identity to its locked filename
ok - recovery rejects close markers targeting another home's data
ok - recovery validates an unterminated final marker field
ok - recovery rejects lexical traversal before resolving marker data
ok - recovery rejects marker control bytes before parsing
ok - recovery rejects malformed PR URL values
ok - a retained pending close is never started by reconciliation
ok - recovery rejects close-marker arguments outside its protocol
ok - recovery reports and rejects dangling symlink close markers
ok - session start drops a close recorded for an older meta incarnation
ok - session start rejects an unversioned close marker
ok - bootstrap rechecks worker-record containment after locking
ok - lifecycle files reject ancestor symlinks outside home roots
ok - same-home state overrides remain supported
ok - bootstrap refuses symlinked state before reconciliation
ok - bootstrap data-disappears fault injection is PATH-based; skipped on Darwin where stat is /usr/bin/stat
ok - bootstrap preserves secondmate, manual, and absent-backlog exemptions
ok - session start leaves a captain-held item where the captain put it
ok - no-backlog teardown refuses symlinked records before resource actions
ok - teardown rechecks record parents after locking
ok - teardown refuses symlinked state before resource actions
ok - a home with no backlog remains exempt from lifecycle transitions
ok - spawn refuses a special-file tasks-axi config instead of blocking on it
ok - spawn refuses an unsafe tasks-axi config before any exemption is derived from it
ok - spawn refuses a data directory symlinked outside the home
ok - a configured adapter refuses a data directory outside the home
ok - dispatch and completion transition structurally with evidence
ok - refused teardown leaves the backlog item in flight
ok - environment-selected adapters bypass the legacy markdown file override
ok - a manual-backlog home dispatches and completes without a hard failure
ok - a secondmate home keeps its own books paired through dispatch and completion
ok - dispatching a persistent secondmate needs no backlog item

Pipeline

Updates from git push no-mistakes

✅ **intent** - passed

✅ No issues found.

🔧 **Rebase** - 1 issue found → auto-fixed ✅

⚠️ tests/fm-backlog-atomicity.test.sh - merge conflict rebasing onto origin/main

🔧 Fix applied.
✅ Re-checked - no issues remain.

🔧 **Review** - 1 issue found → auto-fixed (10) ✅

🚨 bin/fm-fleet-snapshot.sh:462 - The criterion requires “Keep genuine local-only landing evidence while rejecting ordinary prose.” Any completed row whose final body line is exactly local <branch> is still projected as a landing note (bin/fm-fleet-snapshot.sh:462-463,538-540), so ordinary prose local office with no merge reaches Recently Landed via bin/fm-landed-lib.sh:65-69. The regression only rejects prose when another line follows it (tests/fm-fleet-snapshot-view.test.sh:591-593). Decide whether to add an unambiguous marker/metadata or explicitly authorize this final-line convention as containment.

🔧 Fix applied.
1 warning still open:

⚠️ bin/fm-teardown.sh:1636 - When no base_branch is recorded, teardown hardcodes landing=main at this changed site, but fm-merge-local.sh selects the repository default (including master or origin/HEAD). A local-only task on such a repository is merged into the real default while its backlog artifact is recorded as local main, so fleet projections report the wrong landing branch. Use landing_branch for both paths; its sibling selector is at bin/fm-teardown.sh:1350-1359.

🔧 Fix applied.
1 warning still open:

⚠️ tests/fm-named-branches.test.sh:49 - The new named-branch suite proves several behaviors only by grepping generated natural-language briefs/instructions, which can pass even if runtime launch, review, or landing behavior is broken. Refine or remove these source-content-only assertions at tests/fm-named-branches.test.sh:47-52,58,65-73,98-100,237-240,317-318,333-334; assert observable metadata, refs, or command outcomes instead.