feat(harness): add GitHub remote workspace backend#70
Merged
Conversation
Introduce the exchange.RemoteWorkspace ABI and route the existing HTTP mnemon-hub sync client through it for both manual sync commands and the sync worker. Remote configs now carry an explicit backend field while preserving empty-backend compatibility with HTTP. Validation: go test ./harness/internal/mnemonhub/exchange ./harness/internal/app ./harness/cmd/mnemon-harness -run 'TestSync|TestRemote|TestLoadRemoteEntry'; go build -o /tmp/mnemon-harness-check ./harness/cmd/mnemon-harness.
Add coreguard coverage for the GitHub Remote Workspace direction: core packages must not import the future GitHub backend, GitHub backend code must live under mnemonhub/exchange/backend, and backend vocabulary must avoid GitHub Issue/PR/Actions and P2P networking concepts. Validation: go test ./harness/internal/coreguard.
Add Remote Workspace direction semantics and a shared RemotePlan resolver so manual sync and the in-process worker can route publish and subscribe flows without changing the runtime sync ABI. Legacy HTTP configs without explicit directions keep using the current remote bidirectionally. Directional configs fail closed for unknown directions and for multiple active publish targets. Validation: go test ./harness/internal/mnemonhub/exchange ./harness/internal/app ./harness/cmd/mnemon-harness -run 'TestSync|TestRemote|TestLoadRemote|TestRemotePlan'; go test ./harness/internal/coreguard; go build -o /tmp/mnemon-harness-check ./harness/cmd/mnemon-harness.
Resolve run-root and .testdata through physical paths before comparing containment. This keeps the guard behavior intact while avoiding false rejections on systems where temp paths cross symlinked prefixes such as /var and /private/var. Validation: go test ./harness/cmd/mnemon-harness -run 'TestPrepareR1AcceptanceRunRoot|TestSync|TestRemote|TestLoadRemote|TestRemotePlan'; go test ./harness/...; go build -o /tmp/mnemon-harness-check ./harness/cmd/mnemon-harness.
Consume SyncPullResponse diagnostics through the same trusted sync import path as remote events. Pull-side Remote Workspace diagnostics now become sync.remote_diagnostic.observed observations and durable sync.diagnostic entries, with deterministic external ids for repeat-pull dedupe. Validation: go test ./harness/internal/app ./harness/internal/mnemond/policy ./harness/cmd/mnemon-harness -run 'TestSync|TestDiagnostic|TestWorkerPullRemoteDiagnostic|TestPrepareR1AcceptanceRunRoot'; go test ./harness/...; go build -o /tmp/mnemon-harness-check ./harness/cmd/mnemon-harness.
Introduce a repository-shaped PublicationStore interface plus deterministic in-memory implementation for Remote Workspace publication backends. The fake store validates publication branches and paths, supports idempotent event puts, conflict detection, event listing cursors, and team metadata file reads/writes without any GitHub API dependency. Validation: go test ./harness/internal/mnemonhub/exchange -run 'TestPublicationStore'; go test ./harness/...; go build -o /tmp/mnemon-harness-check ./harness/cmd/mnemon-harness.
Implement a GitHub-backed RemoteWorkspace skeleton over PublicationStore without any real GitHub API dependency. The backend publishes synced envelopes to publication paths, treats repeated identical puts as idempotent, reports same-key body conflicts, filters own-origin pulls, and returns pull diagnostics for invalid, out-of-scope, or digest-mismatched publication entries. Validation: go test ./harness/internal/mnemonhub/exchange/backend/github ./harness/internal/mnemonhub/exchange ./harness/internal/app -run 'TestGitHubBackendFake|TestPublicationStore|TestSync'; go test ./harness/internal/coreguard; go test ./harness/...; go build -o /tmp/mnemon-harness-check ./harness/cmd/mnemon-harness.
Teach Remote Workspace config and sync connect about the GitHub publication backend shape: backend, direction, repo, and publication branch. HTTP connect keeps its legacy bidirectional config shape unless a direction is explicitly needed, while GitHub connect validates owner/repo and mnemon/* branch names before writing remotes.json. Validation: go test ./harness/internal/mnemonhub/exchange ./harness/cmd/mnemon-harness -run 'TestSyncConnect|TestSyncRemote|TestLoadRemote|TestRemotePlan|TestPrepareR1AcceptanceRunRoot'; go test ./harness/...; go test ./harness/internal/coreguard; go build -o /tmp/mnemon-harness-check ./harness/cmd/mnemon-harness.
Implement the real GitHub PublicationStore adapter behind the existing RemoteWorkspace backend using Contents API file reads/writes and References API branch-head cursors. The adapter preserves append-only event put semantics, supports metadata file updates with SHA, recursively lists publication event entries, and wires backend=github into CLI and worker factories. Validation: go test ./harness/internal/mnemonhub/exchange/backend/github ./harness/internal/mnemonhub/exchange ./harness/internal/app ./harness/cmd/mnemon-harness -run 'TestGitHub|TestPublicationStore|TestSync'; go test ./harness/internal/coreguard; go test ./harness/...; go build -o /tmp/mnemon-harness-check ./harness/cmd/mnemon-harness.
Add a deterministic five-mnemond acceptance-style test over the fake GitHub publication backend. Each isolated runtime uses its own principal and branch, publishes only to its own stream, subscribes to the other streams, and verifies assignment material converges through the normal sync worker import path. Validation: go test ./harness/internal/app ./harness/internal/mnemonhub/exchange/backend/github -run 'TestSyncGitHubFakeFiveMnemondPublicationMesh|TestGitHub|TestPublicationStore'; go test ./harness/...; go build -o /tmp/mnemon-harness-check ./harness/cmd/mnemon-harness.
Add a GitHub-backed Remote Workspace acceptance entrypoint that configures five isolated Codex appserver workspaces with one dedicated mnemond store each. The setup writes self publish and peer subscribe remotes for repo-mediated publication branches, records repo/branch/store/workspace evidence in the report, and asserts no central mnemon-hub endpoint is present. Validation: go test ./harness/cmd/mnemon-harness -run 'TestR1GitHubMesh|TestWriteR1GitHubMesh|TestBuildR1GitHubMesh|TestPrepareR1AcceptanceRunRoot'; go test ./harness/...; go test ./harness/internal/coreguard; go build -o /tmp/mnemon-harness-check ./harness/cmd/mnemon-harness.
Extend the GitHub mesh acceptance command from topology setup into a natural task-suite runner. PoC agents receive the natural user messages from the architecture plan, non-entry agents only get generic Mnemon wake prompts, profiles are bootstrapped and required to converge through publication branches, and the report records prompt rounds, entry PoC agents, participants, and event-backed scenario evidence. Validation: go test ./harness/cmd/mnemon-harness -run 'TestR1GitHubMesh|TestWriteR1GitHubMesh|TestBuildR1GitHubMesh|TestPrepareR1AcceptanceRunRoot'; go test ./harness/...; go test ./harness/internal/coreguard; go build -o /tmp/mnemon-harness-check ./harness/cmd/mnemon-harness.
Keep opaque GitHub publication cursors behind the Remote Workspace backend so local mnemond pull state continues to persist numeric cursors. This lets GitHub listing rely on Event Intake idempotency without leaking branch head SHAs into the local exchange state. Validation: go test ./harness/internal/mnemonhub/exchange/backend/github; go test ./harness/internal/mnemonhub/exchange ./harness/internal/app
Add an opt-in live test for the GitHub publication backend that drives two isolated mnemond runtimes through Remote Workspace publish, pull, and Event Intake import in both directions. The default path skips unless MNEMON_GITHUB_LIVE=1 and a token are provided. Validation: go test ./harness/internal/app -run TestGitHubLivePublishPullImport -count=1 -v; go test ./harness/internal/app; go test ./harness/internal/mnemonhub/exchange/backend/github ./harness/internal/mnemonhub/exchange
Extend the GitHub mesh acceptance report with repo-mediated transport semantics, configured branch roster evidence, no-p2p discovery, per-workspace remote plans, profile convergence details, and natural multi-round scenario prompt counts. The runner now uses a GitHub-specific worker wake prompt that allows agents to refresh their profile through Local Mnemon without adding a new networking concept. Validation: go test ./harness/cmd/mnemon-harness -run 'TestR1GitHubMesh|TestBuildR1GitHubMesh|TestWriteR1GitHubMesh|TestGitHubMesh' -count=1; go test ./harness/cmd/mnemon-harness; go build -o /tmp/mnemon-harness-check ./harness/cmd/mnemon-harness
Extend the deterministic GitHub publication mesh test to model five initial mnemond runtimes, two later joining publication branches, one paused node, an active-node reassignment event, and eventual catch-up by the paused node. The test keeps discovery explicit through branch subscriptions and does not introduce p2p node discovery. Validation: go test ./harness/internal/app -run 'TestSyncGitHubFake' -count=1 -v; go test ./harness/internal/app
Update the GitHub decentralized Remote Workspace architecture notes with the implementation checkpoint, current validation coverage, no-p2p evidence fields, live GitHub test command, and remaining external evidence required before goal closure. Validation: documentation-only change; confirmed .mnemon-dev is ignored and force-added only the two GitHub architecture files requested for this work.
Document the experimental GitHub Remote Workspace backend as repo-mediated publication branches, with explicit publish/subscribe setup examples and the gated live validation command. Keep mnemon-hub named as the first-party Remote Workspace backend and call out that GitHub does not add P2P discovery or GitHub-native teamwork semantics. Validation: documentation-only change.
Strengthen the GitHub mesh natural acceptance runner so each scenario must produce actual governed assignment and progress_digest evidence, not just multiple runner prompts. The report now records per-actor event counts and adds a post-scenario profile refresh assertion for work-time profile updates. Validation: go test ./harness/cmd/mnemon-harness -run 'TestR1GitHubMesh|TestBuildR1GitHubMesh|TestWriteR1GitHubMesh|TestGitHubMesh' -count=1; go test ./harness/cmd/mnemon-harness; go build -o /tmp/mnemon-harness-check ./harness/cmd/mnemon-harness
Add lifecycle evidence to the GitHub mesh acceptance report and pause/restart one isolated Local Mnemon after appserver initialization. The probe records the configured publication branch and proves the appserver can keep its own mnemond/store/workspace boundary through restart without adding node discovery. Validation: go test ./harness/cmd/mnemon-harness -run 'TestR1GitHubMesh|TestBuildR1GitHubMesh|TestWriteR1GitHubMesh|TestGitHubMesh' -count=1; go test ./harness/cmd/mnemon-harness; go build -o /tmp/mnemon-harness-check ./harness/cmd/mnemon-harness
Update the GitHub Remote Workspace architecture notes to reflect the real mnemon-dev/mnemon-teamwork-example validation. The live publish/pull/import case initially exposed missing publication branches, then passed after initializing mnemon/agent-a through mnemon/agent-e. Validation: MNEMON_GITHUB_LIVE=1 MNEMON_GITHUB_REPO=mnemon-dev/mnemon-teamwork-example MNEMON_GITHUB_TOKEN_FILE=<temp-file> MNEMON_GITHUB_BRANCH_A=mnemon/agent-a MNEMON_GITHUB_BRANCH_B=mnemon/agent-b go test ./harness/internal/app -run TestGitHubLivePublishPullImport -count=1 -v
Move GitHub-backed publication entries out of .mnemonhub-style hash paths and into a visible mnemon-publications/v1/events/<origin>/<kind>/<resource>/<seq>-<decision>.json layout. Keep idempotent same-path semantics while making repo contents easier to review and maintain. Validation: go test ./harness/internal/mnemonhub/exchange ./harness/internal/mnemonhub/exchange/backend/github ./harness/internal/app; go test ./harness/cmd/mnemon-harness; live GitHub gated publication store smoke and app publish/pull/import against mnemon-dev/mnemon-teamwork-example; go build -o /tmp/mnemon-harness-check ./harness/cmd/mnemon-harness.
Teach the GitHub publication store to initialize missing publication branches from main and make the real GitHub mesh acceptance runner default to run-scoped branches. This prevents fresh appserver acceptance runs from importing historical events from long-lived mnemon/agent-* branches while still allowing operators to pass an explicit branch prefix for manual smoke tests. Validation: go test ./harness/internal/mnemonhub/exchange ./harness/internal/mnemonhub/exchange/backend/github ./harness/internal/app ./harness/cmd/mnemon-harness; real GitHub acceptance preflight created mnemon/acceptance/20260625T190648Z/agent-a..e and passed topology/remote-plan assertions before the expected --agent-turns gate; live GitHub publish/pull/import passed on the run-scoped agent-a/b branches; go build -o /tmp/mnemon-harness-check ./harness/cmd/mnemon-harness.
Add a GitHub mesh acceptance sync interval flag and default real GitHub polling to 30 seconds per local mnemond. The previous 100ms interval was suitable for fake/local tests but can overwhelm the real GitHub API during five-node appserver validation. Validation: go test ./harness/cmd/mnemon-harness -run 'TestR1GitHubMesh' -count=1; go test ./harness/cmd/mnemon-harness; go build -o /tmp/mnemon-harness-check ./harness/cmd/mnemon-harness. A real five-node smoke after the previous commit was stopped after GitHub returned secondary rate-limit 403s, which this commit addresses.
Add machine-readable publication, import, diagnostic, and profile summaries to the GitHub mesh acceptance report. The summaries are derived from local governed stores via acceptance observe, so they strengthen P8 evidence without adding GitHub API traffic. Validation: go test ./harness/cmd/mnemon-harness -run 'TestObserveAcceptanceRunReadsMnemondAndHubEvents|TestR1GitHubMesh|TestPopulateR1GitHubMeshSyncEvidence' -count=1; go test ./harness/cmd/mnemon-harness; go test ./harness/internal/mnemonhub/exchange ./harness/internal/mnemonhub/exchange/backend/github ./harness/internal/app; go build -o /tmp/mnemon-harness-check ./harness/cmd/mnemon-harness.
Carry GitHub retry and rate-limit headers through backend API errors so live acceptance failures can distinguish temporary cooldown from auth or repo misconfiguration. Document the diagnostic requirement in the GitHub mesh plan. Validation: go test ./harness/internal/mnemonhub/exchange/backend/github -run 'TestGitHubPublicationStore(RateLimit|EnsureBranch|PutEvent|ListEvents)' -count=1; go test ./harness/internal/mnemonhub/exchange ./harness/internal/mnemonhub/exchange/backend/github ./harness/internal/app ./harness/cmd/mnemon-harness; go build -o /tmp/mnemon-harness-check ./harness/cmd/mnemon-harness.
Extend the GitHub mesh appserver acceptance runner so P8 can keep five publication streams configured while starting a smaller initial online set, activate two delayed mnemond/appserver pairs during the natural task flow, and record join plus pause/restart lifecycle evidence in the report. Validation: go test ./harness/cmd/mnemon-harness; go test ./harness/internal/mnemonhub/exchange ./harness/internal/mnemonhub/exchange/backend/github ./harness/internal/app; go build -o /tmp/mnemon-harness-check ./harness/cmd/mnemon-harness.
Record machine-readable natural-suite evidence for multi-PoC runs, prior completed scenarios, cross-task reuse candidates, and output-driven replanning in the GitHub mesh appserver report. Keep these assertions tied to selected scenarios so focused smoke runs remain usable. Validation: go test ./harness/cmd/mnemon-harness; go test ./harness/internal/mnemonhub/exchange ./harness/internal/mnemonhub/exchange/backend/github ./harness/internal/app; go build -o /tmp/mnemon-harness-check ./harness/cmd/mnemon-harness.
Remove the acceptance-specific branch namespace from the GitHub mesh runner and docs. Default real runs now create publication branches as run-scoped mnemond ids such as mnemon/mnemond-<run-id>-a, keeping branches as mnemond publication streams rather than acceptance concepts or hostagent names. Also add batched GitHub branch ensure so acceptance branch initialization reads the base ref once, de-duplicates branches, and reports branch-specific create failures. Validation: go test ./harness/cmd/mnemon-harness; go test ./harness/internal/mnemonhub/exchange ./harness/internal/mnemonhub/exchange/backend/github ./harness/internal/app; go build -o /tmp/mnemon-harness-check ./harness/cmd/mnemon-harness.
Set a mutative delay when the GitHub mesh acceptance runner creates run-scoped mnemond publication branches, reducing the chance that branch initialization trips GitHub secondary rate limits. Validation: go test ./harness/cmd/mnemon-harness -run 'TestR1GitHubMesh|TestSetupR1CodexGitHubMeshAgentsCanDelayLocalMnemondStart' -count=1; go build -o /tmp/mnemon-harness-check ./harness/cmd/mnemon-harness.
Use a GitHub-mesh-specific topology assertion that requires zero central mnemon-hub instances, and give lifecycle pause enough time to drain an in-flight GitHub sync request before failing the real appserver suite. Validation: go test ./harness/cmd/mnemon-harness; go test ./harness/internal/mnemonhub/exchange ./harness/internal/mnemonhub/exchange/backend/github ./harness/internal/app; go build -o /tmp/mnemon-harness-check ./harness/cmd/mnemon-harness.
Strengthen the natural GitHub mesh scenario entry prompts so the user asks for teamwork through Mnemon without prescribing exact agents or a fixed assignment graph. This keeps the acceptance natural while making the expected teamwork surface explicit enough for real appserver runs. Validation: go test ./harness/cmd/mnemon-harness -run 'TestR1GitHubMesh|TestSetupR1CodexGitHubMeshAgentsCanDelayLocalMnemondStart' -count=1; go build -o /tmp/mnemon-harness-check ./harness/cmd/mnemon-harness.
Let the GitHub mesh natural suite continue once the entry PoC publishes governed assignments, then wake workers, exercise delayed join and lifecycle, and count authored evidence from each local mnemond instead of hub-only cross events. Validation: go test ./harness/cmd/mnemon-harness -count=1; go test ./harness/internal/mnemonhub/exchange ./harness/internal/mnemonhub/exchange/backend/github ./harness/internal/app -count=1; go build -o /tmp/mnemon-harness-check ./harness/cmd/mnemon-harness; live onboarding smoke passed at /tmp/mnemon-github-mesh-onboarding-20260625T211127Z/report.json.
Make delayed join profile convergence wait according to the GitHub sync interval so late joining mnemond instances are not failed before the next publication pull can arrive. Validation: go test ./harness/cmd/mnemon-harness -count=1; go test ./harness/internal/mnemonhub/exchange ./harness/internal/mnemonhub/exchange/backend/github ./harness/internal/app -count=1; go build -o /tmp/mnemon-harness-check ./harness/cmd/mnemon-harness; live sync-risk-review smoke passed at /tmp/mnemon-github-mesh-sync-risk-20260625T215846Z/report.json.
Remove the previously forced .mnemon-dev architecture notes from the branch while leaving the ignored local files in place. The implementation and tests remain under harness and docs/harness.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Validation
Notes