chore(pylon): establish fork governance and sync

Author: pylon-upstream-sync[bot]

.github/CODEOWNERS

@@ -0,0 +1,6 @@
+# Pylon fork governance and synchronization
+/.github/workflows/ @rynfar
+/scripts/pylon-sync-upstream.sh @rynfar
+/AGENTS.md @rynfar
+/PYLON.md @rynfar
+/.pylon/ @rynfar

.github/workflows/changelog-fragment.yml

@@ -3,7 +3,7 @@ name: Changelog fragment
 on:
   pull_request:
     types: [opened, synchronize, reopened, labeled, unlabeled]
-    branches: [main]
+    branches: [pylon]
 
 permissions:
   pull-requests: read

.github/workflows/ci.yml

@@ -1,13 +1,20 @@
 name: CI
 
 on:
+  workflow_call:
+    inputs:
+      checkout_ref:
+        description: Exact candidate commit to verify from a trusted Pylon workflow
+        required: false
+        type: string
   push:
-    branches: [main]
+    branches: [pylon]
   pull_request:
-    branches: [main]
+    branches: [pylon]
+    types: [opened, synchronize, reopened, ready_for_review]
 
 concurrency:
-  group: ci-${{ github.ref }}
+  group: ci-${{ inputs.checkout_ref || github.ref }}
   cancel-in-progress: true
 
 permissions:
@@ -16,13 +23,26 @@ permissions:
 jobs:
   trust:
     name: Contributor trust
+    if: github.event_name != 'pull_request' || github.event.pull_request.draft == false
     runs-on: ubuntu-latest
     outputs:
-      allowed: ${{ github.event_name == 'push' || steps.vouch.outputs.vouched == 'true' }}
+      allowed: ${{ github.event_name == 'workflow_call' || github.event_name == 'push' || steps.sync.outputs.allowed == 'true' || steps.vouch.outputs.vouched == 'true' }}
     steps:
+      - name: Recognize the internal upstream sync pull request
+        id: sync
+        if: github.event_name == 'pull_request'
+        env:
+          HAS_SYNC_LABEL: ${{ contains(github.event.pull_request.labels.*.name, 'pylon-upstream-sync') }}
+          HEAD_REF: ${{ github.event.pull_request.head.ref }}
+          HEAD_REPOSITORY: ${{ github.event.pull_request.head.repo.full_name }}
+        run: |
+          if [ "$HAS_SYNC_LABEL" = true ] && [ "$HEAD_REPOSITORY" = "pylon-code/prime-agent" ] && [[ "$HEAD_REF" == automation/prime-upstream-* ]]; then
+            echo "allowed=true" >> "$GITHUB_OUTPUT"
+          fi
+
       - name: Check pull request author
         id: vouch
-        if: github.event_name == 'pull_request'
+        if: github.event_name == 'pull_request' && steps.sync.outputs.allowed != 'true'
         uses: mitchellh/vouch/action/check-user@d66fa29a64600490892131ad87597c30c91fcac4 # v1
         with:
           user: ${{ github.event.pull_request.user.login }}
@@ -40,6 +60,7 @@ jobs:
       - name: Checkout
         uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
         with:
+          ref: ${{ inputs.checkout_ref || github.ref }}
           persist-credentials: false
 
       - name: Setup Node.js
@@ -52,7 +73,7 @@ jobs:
         run: |
           sudo apt-get update
           sudo apt-get install -y libcairo2-dev libpango1.0-dev libjpeg-dev libgif-dev librsvg2-dev fd-find ripgrep
-          sudo ln -s $(which fdfind) /usr/local/bin/fd
+          sudo ln -s "$(which fdfind)" /usr/local/bin/fd
 
       - name: Install dependencies
         run: npm ci
@@ -113,6 +134,7 @@ jobs:
       - name: Checkout
         uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
         with:
+          ref: ${{ inputs.checkout_ref || github.ref }}
           persist-credentials: false
 
       - name: Setup Node.js
@@ -125,7 +147,7 @@ jobs:
         run: |
           sudo apt-get update
           sudo apt-get install -y libcairo2-dev libpango1.0-dev libjpeg-dev libgif-dev librsvg2-dev fd-find ripgrep
-          sudo ln -s $(which fdfind) /usr/local/bin/fd
+          sudo ln -s "$(which fdfind)" /usr/local/bin/fd
 
       - name: Install dependencies
         run: npm ci

.github/workflows/pylon-upstream-sync.yml

@@ -0,0 +1,47 @@
+name: Pylon upstream sync
+
+on:
+  schedule:
+    - cron: "17 7 * * *"
+  workflow_dispatch:
+
+concurrency:
+  group: pylon-upstream-sync
+  cancel-in-progress: false
+
+permissions:
+  contents: write
+  issues: write
+  pull-requests: write
+
+jobs:
+  sync:
+    name: Mirror and prepare merge
+    if: github.repository == 'pylon-code/prime-agent' && github.ref == 'refs/heads/pylon'
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    outputs:
+      candidate_sha: ${{ steps.sync.outputs.candidate_sha }}
+      pr_url: ${{ steps.sync.outputs.pr_url }}
+    steps:
+      - name: Checkout Pylon product branch
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          ref: pylon
+          fetch-depth: 0
+
+      - name: Mirror Prime and open a draft merge pull request
+        id: sync
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: scripts/pylon-sync-upstream.sh
+
+  verify:
+    name: Verify candidate with trusted fork CI
+    needs: sync
+    if: needs.sync.outputs.candidate_sha != ''
+    permissions:
+      contents: read
+    uses: ./.github/workflows/ci.yml
+    with:
+      checkout_ref: ${{ needs.sync.outputs.candidate_sha }}

.pylon/features.yaml

@@ -0,0 +1,115 @@
+schema: 1
+fork:
+  repository: https://github.com/pylon-code/prime-agent
+  upstream_repository: https://github.com/PrimeIntellect-ai/prime-agent
+  upstream_branch: main
+  mirror_branch: main
+  product_branch: pylon
+  tracking_issue: https://github.com/pylon-code/prime-agent/issues/1
+  reviewed_upstream_commit: bc0fa7606abb3b7af0f765319518d255e6ae553d
+  reviewed_at: 2026-08-27
+
+decisions:
+  managed-plan-daemon:
+    area: progress
+    state: shipped
+    owner: pylon-server
+    decision: retain
+    pylon_refs:
+      - https://github.com/pylon-code/pylon/issues/114
+      - https://github.com/pylon-code/pylon/pull/116
+    fork_change: none
+    upstream_support: Prime extensions can register a todo tool, but the daemon has no native managed-plan event.
+    revisit_when:
+      - Prime ships a negotiated structured plan event or equivalent managed tool-result contract.
+      - Pylon behavioral evaluation shows the full-snapshot model is too noisy or unreliable.
+
+  managed-plan-acp:
+    area: progress
+    state: gap
+    owner: pylon-prime-integration
+    decision: redesign
+    pylon_refs:
+      - https://github.com/pylon-code/pylon/issues/114
+    fork_change: candidate
+    upstream_support: ACP does not expose a trustworthy Pylon-managed structured plan result.
+    revisit_when:
+      - Prime adds authenticated extension provenance and structured ACP tool-result metadata.
+      - A standard ACP plan protocol becomes available.
+
+  mobile-plan-rendering:
+    area: progress
+    state: gap
+    owner: pylon-client
+    decision: retain
+    pylon_refs:
+      - https://github.com/pylon-code/pylon/issues/114
+    fork_change: none
+    upstream_support: not applicable
+    revisit_when:
+      - Pylon mobile and web share a provider-neutral plan renderer.
+
+  delegated-work-progress:
+    area: progress
+    state: design
+    owner: pylon-client-runtime
+    decision: redesign
+    pylon_refs:
+      - https://github.com/pylon-code/pylon/issues/114
+    fork_change: possible-capability
+    upstream_support: Prime exposes subagent lifecycle separately from root plan state.
+    revisit_when:
+      - Root progress can summarize delegated phases without creating one plan row per worker.
+      - Prime exposes a stable aggregate delegated-work status where Pylon lacks one.
+
+  background-process-lifecycle:
+    area: autonomous-work
+    state: gap
+    owner: shared
+    decision: hybridize
+    pylon_refs:
+      - https://github.com/pylon-code/pylon/issues/114
+    fork_change: candidate
+    upstream_support: Prime has native background execution, but Pylon lacks complete public lifecycle and ownership mapping.
+    revisit_when:
+      - Prime publishes list, correlation, cancellation, and terminal lifecycle events.
+
+  heartbeat-projection:
+    area: autonomous-work
+    state: blocked
+    owner: shared
+    decision: hybridize
+    pylon_refs:
+      - https://github.com/pylon-code/pylon/issues/114
+    fork_change: none-yet
+    upstream_support: Prime exposes heartbeat list, management, and change APIs.
+    blocker: Pylon needs canonical autonomous occurrence, turn, checkpoint, and active-run ownership.
+    revisit_when:
+      - The provider-neutral autonomous-work ownership model is implemented.
+      - Prime changes heartbeat dispatch or lifecycle APIs.
+
+  scheduled-prompts:
+    area: autonomous-work
+    state: blocked
+    owner: shared
+    decision: redesign
+    pylon_refs:
+      - https://github.com/pylon-code/pylon/issues/114
+    fork_change: candidate
+    upstream_support: Prime exposes scheduled prompt APIs, but not all Pylon run ownership and history guarantees.
+    blocker: Pylon needs canonical occurrence identity, restart adoption, cancellation, outcomes, limits, and checkpoint ownership.
+    revisit_when:
+      - The provider-neutral autonomous-work ownership model is implemented.
+      - Prime publishes stronger scheduled-run lifecycle APIs.
+
+  pylon-read-context:
+    area: agent-context
+    state: gap
+    owner: pylon-server
+    decision: retain
+    pylon_refs:
+      - https://github.com/pylon-code/pylon/issues/114
+    fork_change: none
+    upstream_support: not applicable
+    revisit_when:
+      - Pylon ships scoped read-only context and checkpoint MCP capabilities.

.pylon/upstream-review.md

@@ -0,0 +1,25 @@
+# Pylon upstream review ledger
+
+This ledger records Prime upstream evidence and the decision taken for each overlapping Pylon feature. `.pylon/features.yaml` is the current machine-readable state; this file is the chronological review record.
+
+## Entry template
+
+- Date and upstream commit or release
+- Prime issues, pull requests, releases, and source reviewed
+- Affected feature keys from `.pylon/features.yaml`
+- Decision: `adopt`, `hybridize`, `retain`, or `redesign`
+- Reason and Pylon constraints
+- Validation performed
+- Follow-up or revisit trigger
+
+## 2026-08-27 — fork baseline
+
+- Upstream baseline: `PrimeIntellect-ai/prime-agent@bc0fa7606abb3b7af0f765319518d255e6ae553d`
+- Latest audited release: `v0.8.1`
+- Reviewed Prime's extension todo example, daemon plan and heartbeat APIs, ACP event surface, background execution work, releases, and related public issues and pull requests.
+- `managed-plan-daemon`: **retain** Pylon's allowlisted full-snapshot managed extension. Prime has an extension example, not an equivalent reconnect-safe managed daemon plan contract.
+- `managed-plan-acp`: **redesign** as a small capability-gated fork bridge. Do not expose arbitrary extension tool details.
+- `delegated-work-progress`: **redesign** around phase-level root progress plus the separate Agents surface. Do not create one plan item per subagent.
+- `heartbeat-projection` and `background-process-lifecycle`: **hybridize** after Pylon defines provider-neutral autonomous occurrence and checkpoint ownership.
+- `scheduled-prompts`: **redesign** after the same ownership foundation. Prime's native scheduling is useful but is not itself Pylon's durable cross-provider scheduler model.
+- No fork source behavior was added at baseline. The first fork change should target a measured Pylon parity gap and include stock-Prime degradation tests.

AGENTS.md

@@ -1,5 +1,9 @@
 # Development Rules
 
+## Pylon fork policy
+
+On the `pylon` branch and branches based on it, read and follow `PYLON.md` before making changes. `main` is an exact Prime upstream mirror; all Pylon product work targets `pylon`. When upstream and Pylon overlap, preserve Pylon behavior until `.pylon/features.yaml` records a reviewed `adopt`, `hybridize`, `retain`, or `redesign` decision.
+
 ## Conversational Style
 
 - No fluff or cheerful filler text
@@ -71,9 +75,10 @@ When closing issues via commit:
 
 ## PR Workflow
 
-- Analyze PRs without pulling locally first
-- If the user approves: create a feature branch, pull PR, rebase on main, apply adjustments, commit, merge into main, push, close PR, and leave a comment in the user's tone
-- We work in feature branches until everything is according to the user's requirements. Never merge PRs by yourself.
+- Analyze PRs without pulling locally first.
+- For Pylon product work, branch from the latest `origin/pylon`, apply adjustments, commit only your files, push the task branch, and open a pull request against `pylon`.
+- Never commit or merge Pylon changes into `main`; it is the exact Prime upstream mirror.
+- We work in feature branches until everything meets the user's requirements. Never merge pull requests by yourself.
 
 ## Testing Prime Agent Interactive Mode with tmux
 

PYLON.md

@@ -0,0 +1,42 @@
+# Pylon Prime Agent fork
+
+This repository is Pylon's long-lived Prime Agent fork. It follows Prime upstream closely while allowing Pylon-owned integration behavior to remain when upstream has no suitable equivalent.
+
+## Branches and remotes
+
+- `main` is an exact fast-forward mirror of `PrimeIntellect-ai/prime-agent:main`. Never commit Pylon changes to it.
+- `pylon` is the default product branch. Branch feature work from the latest `origin/pylon` and open pull requests back to `pylon`.
+- The local `upstream` remote must be fetch-only. Never push to a Prime Intellect remote.
+- Do not hard-reset, force-push, or wholesale rebase `pylon` onto upstream.
+
+The daily `Pylon upstream sync` workflow fast-forwards `main`, then opens a draft merge pull request into `pylon`. Clean candidates run through the trusted `pylon` CI definition with no secrets or persisted Git credentials. A conflict opens or updates one blocker issue and requires a human resolution branch from `pylon`; the workflow never resolves conflicts automatically.
+
+Sync and manual conflict-resolution pull requests must use merge commits so `pylon` retains ancestry from the exact upstream commit. The mirror push must use the built-in `GITHUB_TOKEN`: replacing it with a PAT or app token would allow an upstream-owned push workflow to execute when `main` advances.
+
+## Upstream overlap decisions
+
+Before adding or changing a Pylon-owned integration:
+
+1. Search current Prime Agent issues, pull requests, releases, and source.
+2. Update `.pylon/features.yaml` with the current ownership and upstream evidence.
+3. Choose one explicit decision:
+   - `adopt`: use the upstream implementation and remove the superseded fork behavior;
+   - `hybridize`: use upstream primitives behind a Pylon-owned contract;
+   - `retain`: keep the fork behavior because upstream does not meet Pylon's needs;
+   - `redesign`: replace both implementations with a smaller coherent model.
+4. Capability-gate optional daemon or ACP behavior and keep stock Prime degradation local.
+5. Add the decision and validation result to `.pylon/upstream-review.md`.
+
+Pylon divergence has no expiry date. Remove it only when evidence shows that another implementation genuinely supersedes it.
+
+## Release boundary
+
+Mirroring upstream must not publish packages, binaries, or beta releases. Keep the inherited release workflow disabled in the fork, and never expose upstream-known release secrets at repository scope. Fork artifact names, package ownership, provenance, signing, and release channels require a separate reviewed design before automated publishing is enabled.
+
+## Product integration principles
+
+- Keep orchestration and durable ownership in Pylon when the behavior spans providers.
+- Put Prime-specific protocol translation and missing Prime lifecycle primitives at the fork boundary.
+- Prefer negotiated capabilities to version guesses.
+- Keep structured progress concise. The root plan describes meaningful user-visible outcomes, not every tool call or delegated worker.
+- Preserve a stock-Prime fallback when Pylon can do so without weakening correctness or trust boundaries.

README.md

@@ -12,6 +12,8 @@
 Prime Agent: A Self-Improving RLM Harness
 </h3>
 
+> This is Pylon's long-lived Prime Agent fork. It synchronizes with [Prime upstream](https://github.com/PrimeIntellect-ai/prime-agent) daily while preserving Pylon integrations that upstream does not yet provide. See [PYLON.md](PYLON.md) for branch, synchronization, and overlap policy.
+
 <p align="center">
   <a href="packages/coding-agent/docs/index.md">Documentation</a> &bull;
   <a href="https://github.com/PrimeIntellect-ai/verifiers">Verifiers</a> &bull;