feat(issue-fix): bootstrap LoopX automatically on first start

A fresh user's repository has no .loopx control plane, which previously
surfaced as a raw "Failed to read LoopX Issue-Fix state" error banner
the moment the panel opened. Pre-bootstrap is a normal state, not an
error: status/poll now return null for unconnected repositories, the
header says "not connected yet — select issues and press Start", and
the Start command runs # LoopX Bootstrap

- ok: `True`
- dry_run: `False`
- project: `C:\codeagent\BitFun`
- goal_id: `bitfun-goal`
- registry: `C:\codeagent\BitFun\.loopx\registry.json`
- state_file: `C:\codeagent\BitFun\.codex\goals\bitfun-goal\ACTIVE_GOAL_STATE.md`
- goal_doc: `None`
- goal_doc_exists: `False`
- runtime_root: `C:\Users\huawei\.codex\loopx`
- registry_goal_action: `kept-existing`
- state_action: `kept-existing`
- execution_profile: `cadence=bounded_progress_segment minimum=multi_surface_or_implementation include=coherent_artifact,targeted_validation,state_writeback spend_rule=spend_only_after_artifact_validation_writeback small_streak_threshold=2`
- onboarding_acceptance_required: `True`
- autonomous_advance_choice_required: `True`
- codex_app_heartbeat: `ask`
- heartbeat_opt_in_required: `True`
- host_loop_activation_required: `True`
- onboarding_todos_written: `False`
- global_sync: `True`

## Actions
- `C:\codeagent\BitFun\.loopx\registry.json`: wrote (kept-existing)
- `C:\codeagent\BitFun\.codex\goals\bitfun-goal\ACTIVE_GOAL_STATE.md`: kept-existing ()
- `C:\Users\huawei\.codex\loopx\registry.global.json`: synced (bitfun-goal)

## Onboarding Scan
- schema: `loopx_project_onboarding_v0`
- git_repo: `True`
- status_path_count: `10`
- recent_commits: `5`
- signal_files: `README.md, AGENTS.md, CONTRIBUTING.md, package.json, Cargo.toml`
- raw_file_bodies_read: `False`
- status_sample:
  - `A  BitFun-Installer/src-tauri/Cargo.lock`
  - `M  src/apps/desktop/src/api/issue_fix_api.rs`
  - `M  src/crates/services/services-integrations/src/loopx_issue_fix/autonomous.rs`
  - `M  src/web-ui/src/app/components/panels/issue-fix/IssueFixPanel.tsx`
  - `M  src/web-ui/src/infrastructure/api/service-api/IssueFixAPI.ts`
- recent_commit_sample:
  - `7a0db930d` feat(issue-fix): bundled LoopX sidecar and three-tier readiness probe
  - `441cfc424` Merge remote-tracking branch 'origin/main' into feat/loopx-issue-fix
  - `386d352a3` fix(desktop): also shrink oversized restored windows into the work area
  - `ddf07a48d` fix(issue-fix): make 'Open panel' work from any scene
  - `8fe67c5cb` Merge pull request #2064 from ldc111/main

## Proposed Onboarding Candidates
1. [P1] Inspect current uncommitted changes (A BitFun-Installer/src-tauri/Cargo.lock, M src/apps/desktop/src/api/issue_fix_api.rs, M src/crates/services/services-integrations/src/loopx_issue_fix/autonomous.rs, M src/web-ui/src/app/components/panels/issue-fix/IssueFixPanel.tsx, M src/web-ui/src/infrastructure/api/service-api/IssueFixAPI.ts) and decide what belongs in the first LoopX segment before editing.
   - reason: The repo already has local changes, so the first safe step is ownership and scope classification.
   - metadata: `advancement_task:repo_status_review`
2. [P1] Summarize the last 5 commits and extract the safest next bounded project follow-up.
   - reason: Recent commits are a fast signal of current project direction without reading private bodies.
   - metadata: `advancement_task:commit_summary`
3. [P1] Identify the fastest validation command from package.json, Cargo.toml and record whether it is safe to run now.
   - reason: Validation entrypoints are visible from top-level project metadata.
   - metadata: `advancement_task:validation_plan`
4. [P2] Build a compact read-only project map from README.md, AGENTS.md, CONTRIBUTING.md, package.json, Cargo.toml and note authority sources, risks, and first useful handoff.
   - reason: Top-level project files can seed a useful map before any implementation work.
   - metadata: `advancement_task:read_only_map`

## Accept Candidate Commands
Run only the commands for candidates the user accepts, then refresh state.
- `loopx --registry '.loopx\registry.json' todo add --goal-id bitfun-goal --role agent --text '[P1] Inspect current uncommitted changes (A BitFun-Installer/src-tauri/Cargo.lock, M src/apps/desktop/src/api/issue_fix_api.rs, M src/crates/services/services-integrations/src/loopx_issue_fix/autonomous.rs, M src/web-ui/src/app/components/panels/issue-fix/IssueFixPanel.tsx, M src/web-ui/src/infrastructure/api/service-api/IssueFixAPI.ts) and decide what belongs in the first LoopX segment before editing.' --task-class advancement_task --action-kind repo_status_review`
- `loopx --registry '.loopx\registry.json' todo add --goal-id bitfun-goal --role agent --text '[P1] Summarize the last 5 commits and extract the safest next bounded project follow-up.' --task-class advancement_task --action-kind commit_summary`
- `loopx --registry '.loopx\registry.json' todo add --goal-id bitfun-goal --role agent --text '[P1] Identify the fastest validation command from package.json, Cargo.toml and record whether it is safe to run now.' --task-class advancement_task --action-kind validation_plan`
- `loopx --registry '.loopx\registry.json' todo add --goal-id bitfun-goal --role agent --text '[P2] Build a compact read-only project map from README.md, AGENTS.md, CONTRIBUTING.md, package.json, Cargo.toml and note authority sources, risks, and first useful handoff.' --task-class advancement_task --action-kind read_only_map`

## Autonomy And Heartbeat Choice
- heartbeat_opt_in_instruction: Ask the user whether to enable the Codex App heartbeat. heartbeat=yes means create or update a recurring Codex App automation from an identity-scoped `loopx heartbeat-prompt --thin` task body; heartbeat=no means keep the goal manual or on-demand.
- Ask the user whether Codex may start autonomous advancement. If autonomous=yes, run the quota guard and execute the first accepted Agent Todo; if autonomous=no, stop after writing accepted todos and refresh-state.

## Next Commands
- `loopx --registry .loopx\registry.json registry`
- `loopx --registry .loopx\registry.json status`
- `loopx --registry .loopx\registry.json check --scan-root C:\codeagent\BitFun`
- `loopx --format json --registry C:\Users\huawei\.codex\loopx\registry.global.json quota should-run --goal-id bitfun-goal --runtime-profile generic_cli`
- `loopx --registry .loopx\registry.json refresh-state --goal-id bitfun-goal`
- `loopx --registry C:\Users\huawei\.codex\loopx\registry.global.json status`
- `loopx --registry .loopx\registry.json history --goal-id bitfun-goal`

## Install / Update Hint
If this local LoopX install is missing or stale, rerun the no-clone installer, refresh PATH, and confirm with loopx doctor before continuing project delivery.
```bash
curl -fsSL https://raw.githubusercontent.com/huangruiteng/loopx/main/scripts/install-from-github.sh | bash
export PATH="$HOME/.local/bin:$PATH"
loopx doctor
```

## Boundary Note
Add .loopx/ and .codex/goals/ to the project .gitignore if the goal state contains private evidence. (BitFun's continuous-repair
objective, controller role) plus  before
writing the first intake todos. Verified end to end on a fresh git repo
with the PyInstaller sidecar: bootstrap -> register -> intake -> todo
projection -> compact heartbeat generation all succeed.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: xlx1212

BitFun-Installer/src-tauri/Cargo.lock

@@ -141,8 +141,13 @@ pub struct IssueFixAutonomousStatusResponse {
 pub async fn issue_fix_autonomous_status(
     _state: State<'_, AppState>,
     request: IssueFixAutonomousStatusRequest,
-) -> Result<IssueFixAutonomousStatusResponse, String> {
+) -> Result<Option<IssueFixAutonomousStatusResponse>, String> {
     let repository_path = required_repository_path(&request.repository_path)?;
+    // A repository that has never started continuous fixing has no LoopX
+    // control plane yet; that is a normal pre-bootstrap state, not an error.
+    if !AutonomousIssueFix::is_bootstrapped(repository_path) {
+        return Ok(None);
+    }
     let loopx =
         LoopxIssueFix::probe().ok_or_else(|| "loopx is not installed on this host".to_string())?;
     let control = AutonomousIssueFix::new(loopx)
@@ -153,7 +158,7 @@ pub async fn issue_fix_autonomous_status(
             format!("Failed to read LoopX Issue-Fix state: {error}")
         })?;
     let host_loop = host_loop_state(&control.goal_id, repository_path).await;
-    Ok(IssueFixAutonomousStatusResponse { control, host_loop })
+    Ok(Some(IssueFixAutonomousStatusResponse { control, host_loop }))
 }
 
 /// Background-poll response: LoopX todo projection without `quota should-run`.
@@ -172,8 +177,11 @@ pub struct IssueFixAutonomousPollResponse {
 pub async fn issue_fix_autonomous_poll(
     _state: State<'_, AppState>,
     request: IssueFixAutonomousStatusRequest,
-) -> Result<IssueFixAutonomousPollResponse, String> {
+) -> Result<Option<IssueFixAutonomousPollResponse>, String> {
     let repository_path = required_repository_path(&request.repository_path)?;
+    if !AutonomousIssueFix::is_bootstrapped(repository_path) {
+        return Ok(None);
+    }
     let loopx =
         LoopxIssueFix::probe().ok_or_else(|| "loopx is not installed on this host".to_string())?;
     let light = AutonomousIssueFix::new(loopx)
@@ -184,7 +192,7 @@ pub async fn issue_fix_autonomous_poll(
             format!("Failed to poll LoopX Issue-Fix state: {error}")
         })?;
     let host_loop = host_loop_state(&light.goal_id, repository_path).await;
-    Ok(IssueFixAutonomousPollResponse { light, host_loop })
+    Ok(Some(IssueFixAutonomousPollResponse { light, host_loop }))
 }
 
 #[derive(Debug, Deserialize)]
@@ -306,7 +314,18 @@ pub async fn issue_fix_start_autonomous(
         })
         .collect::<Vec<_>>();
 
-    let plan = AutonomousIssueFix::new(loopx)
+    let autonomous = AutonomousIssueFix::new(loopx);
+    // First use on a fresh repository: create the LoopX goal and the host
+    // agent lane before writing intake todos. No-op when already connected.
+    autonomous
+        .ensure_bootstrapped(repository_path)
+        .await
+        .map_err(|error| {
+            error!("Failed to bootstrap LoopX for continuous Issue-Fix: {error}");
+            format!("Failed to connect this repository to LoopX: {error}")
+        })?;
+
+    let plan = autonomous
         .start(repository_path, request.repo.trim(), &selections)
         .await
         .map_err(|error| {

src/apps/desktop/src/api/issue_fix_api.rs

@@ -16,6 +16,15 @@ use super::{LoopxIssueFix, LoopxIssueFixError};
 const ISSUE_INTAKE_ACTION: &str = "issue_fix_intake";
 const MAX_USER_REASON_CHARS: usize = 240;
 
+/// Default objective for goals BitFun bootstraps itself: one sentence,
+/// repository-agnostic. Per-repo policy accrues in the goal's active state.
+const BOOTSTRAP_OBJECTIVE: &str = "Continuously repair repository issues explicitly \
+selected in BitFun, keep each issue isolated, validate every change, and surface \
+authority gates for human decisions.";
+
+/// The registered agent id BitFun's host loop runs as.
+const BOOTSTRAP_AGENT_ID: &str = "bitfun-cron";
+
 /// Host preamble prepended to LoopX's generated heartbeat contract.
 ///
 /// LoopX owns every lifecycle rule (the `--compact` task body below it); this
@@ -230,6 +239,60 @@ impl AutonomousIssueFix {
         self.inspect_with_identity(repository_path, &identity).await
     }
 
+    /// True when the repository has a usable LoopX control plane (a registry
+    /// with exactly one active goal and one registered agent).
+    pub fn is_bootstrapped(repository_path: &Path) -> bool {
+        read_identity(repository_path).is_ok()
+    }
+
+    /// Bootstrap the repository into LoopX on first use: create the goal with
+    /// BitFun's continuous-repair objective and register the host agent lane.
+    ///
+    /// Idempotent at the call level — when a valid control plane already
+    /// exists this is a no-op. The goal id derives from the directory name,
+    /// mirroring `loopx bootstrap`'s own default.
+    pub async fn ensure_bootstrapped(
+        &self,
+        repository_path: &Path,
+    ) -> Result<(), AutonomousIssueFixError> {
+        if Self::is_bootstrapped(repository_path) {
+            return Ok(());
+        }
+        self.loopx
+            .json_in(
+                repository_path,
+                [
+                    "bootstrap",
+                    "--project",
+                    ".",
+                    "--objective",
+                    BOOTSTRAP_OBJECTIVE,
+                    "--role",
+                    "controller",
+                    "--no-onboarding-scan",
+                ],
+            )
+            .await?;
+        // The goal now exists but carries no registered agents yet, so the
+        // full identity read (which requires exactly one agent) cannot be
+        // used here — read the goal id alone.
+        let goal_id = read_active_goal_id(repository_path)?;
+        self.loopx
+            .json_in(
+                repository_path,
+                [
+                    "register-agent",
+                    "--goal-id",
+                    goal_id.as_str(),
+                    "--agent-id",
+                    BOOTSTRAP_AGENT_ID,
+                    "--execute",
+                ],
+            )
+            .await?;
+        Ok(())
+    }
+
     /// Cheap read-only projection for background polling: `todo list` only.
     ///
     /// Unlike [`Self::inspect`], this never invokes `quota should-run`, which
@@ -523,35 +586,9 @@ fn scheduler_args(
 
 fn read_identity(repository_path: &Path) -> Result<ControlIdentity, AutonomousIssueFixError> {
     let path = repository_path.join(".loopx").join("registry.json");
-    let bytes = std::fs::read(&path).map_err(|source| AutonomousIssueFixError::RegistryRead {
-        path: path.clone(),
-        source,
-    })?;
-    let registry: Value =
-        serde_json::from_slice(&bytes).map_err(|source| AutonomousIssueFixError::RegistryJson {
-            path: path.clone(),
-            source,
-        })?;
-    let active_goals = registry
-        .get("goals")
-        .and_then(Value::as_array)
-        .into_iter()
-        .flatten()
-        .filter(|goal| goal.get("status").and_then(Value::as_str) == Some("active"))
-        .collect::<Vec<_>>();
-    if active_goals.len() != 1 {
-        return Err(AutonomousIssueFixError::ActiveGoalCount(active_goals.len()));
-    }
-    let goal = active_goals[0];
-    let goal_id = goal
-        .get("id")
-        .and_then(Value::as_str)
-        .filter(|value| !value.trim().is_empty())
-        .ok_or(AutonomousIssueFixError::MissingField {
-            command: "registry",
-            field: "goals[].id",
-        })?
-        .to_string();
+    let registry = read_registry(&path)?;
+    let goal = single_active_goal(&registry)?;
+    let goal_id = goal_id_of(goal)?;
     let agents = goal
         .pointer("/coordination/registered_agents")
         .and_then(Value::as_array)
@@ -572,6 +609,50 @@ fn read_identity(repository_path: &Path) -> Result<ControlIdentity, AutonomousIs
     })
 }
 
+/// The active goal id alone, for mid-bootstrap states where the agent lane is
+/// not registered yet.
+fn read_active_goal_id(repository_path: &Path) -> Result<String, AutonomousIssueFixError> {
+    let path = repository_path.join(".loopx").join("registry.json");
+    let registry = read_registry(&path)?;
+    goal_id_of(single_active_goal(&registry)?)
+}
+
+fn read_registry(path: &Path) -> Result<Value, AutonomousIssueFixError> {
+    let bytes = std::fs::read(path).map_err(|source| AutonomousIssueFixError::RegistryRead {
+        path: path.to_path_buf(),
+        source,
+    })?;
+    serde_json::from_slice(&bytes).map_err(|source| AutonomousIssueFixError::RegistryJson {
+        path: path.to_path_buf(),
+        source,
+    })
+}
+
+fn single_active_goal(registry: &Value) -> Result<&Value, AutonomousIssueFixError> {
+    let active_goals = registry
+        .get("goals")
+        .and_then(Value::as_array)
+        .into_iter()
+        .flatten()
+        .filter(|goal| goal.get("status").and_then(Value::as_str) == Some("active"))
+        .collect::<Vec<_>>();
+    if active_goals.len() != 1 {
+        return Err(AutonomousIssueFixError::ActiveGoalCount(active_goals.len()));
+    }
+    Ok(active_goals[0])
+}
+
+fn goal_id_of(goal: &Value) -> Result<String, AutonomousIssueFixError> {
+    goal.get("id")
+        .and_then(Value::as_str)
+        .filter(|value| !value.trim().is_empty())
+        .map(str::to_string)
+        .ok_or(AutonomousIssueFixError::MissingField {
+            command: "registry",
+            field: "goals[].id",
+        })
+}
+
 fn project_issue_todo(todo: &Value) -> Option<AutonomousIssueTodo> {
     if todo.get("role").and_then(Value::as_str) != Some("agent") {
         return None;

src/crates/services/services-integrations/src/loopx_issue_fix/autonomous.rs

@@ -118,6 +118,9 @@ export const IssueFixPanel: React.FC<IssueFixPanelProps> = ({
   // Full readiness picture: loopx presence is `available`; the gh tiers gate
   // guidance banners (the agent's whole evidence/PR channel runs through gh).
   const [readiness, setReadiness] = useState<IssueFixAvailability | null>(null);
+  // True once the control probe answered (even with "not connected"), so the
+  // header can distinguish loading from pre-bootstrap.
+  const [controlProbed, setControlProbed] = useState(false);
   const [loading, setLoading] = useState(false);
   const [running, setRunning] = useState(false);
   const [stopping, setStopping] = useState(false);
@@ -271,7 +274,10 @@ export const IssueFixPanel: React.FC<IssueFixPanelProps> = ({
     const ticket = takeControlTicket();
     try {
       const status = await issueFixAPI.getAutonomousStatus(workspacePath);
+      // Null = repository not connected to LoopX yet (bootstraps on first
+      // Start); distinguish it from "still loading" for the header text.
       applyControl(ticket, () => status);
+      if (mountedRef.current) setControlProbed(true);
     } catch (error) {
       log.error('Failed to project continuous Issue-Fix state', { workspacePath, error });
       if (ticket >= appliedControlTicketRef.current && mountedRef.current) {
@@ -304,7 +310,7 @@ export const IssueFixPanel: React.FC<IssueFixPanelProps> = ({
       const ticket = takeControlTicket();
       try {
         const poll = await issueFixAPI.pollAutonomous(workspacePath);
-        if (cancelled) return;
+        if (cancelled || !poll) return;
         // A beat boundary shows up either as the active turn draining or as
         // the schedule advancing (which also catches beats shorter than one
         // poll interval); each boundary earns one full quota-backed refresh.
@@ -730,7 +736,9 @@ export const IssueFixPanel: React.FC<IssueFixPanelProps> = ({
                   state: control.kernelState,
                   queued: progress.queued,
                 })
-              : t('autonomous.loadingKernel')}
+              : controlProbed
+                ? t('autonomous.notConnected')
+                : t('autonomous.loadingKernel')}
           </span>
           {control && (control.userTodos ?? []).length > 0 ? (
             <button

src/web-ui/src/app/components/panels/issue-fix/IssueFixPanel.tsx

@@ -105,7 +105,14 @@ class IssueFixAPI {
     }
   }
 
-  async getAutonomousStatus(repositoryPath: string): Promise<IssueFixAutonomousStatusResponse> {
+  /**
+   * Full quota-backed projection, or null when the repository has never been
+   * connected to LoopX (pre-bootstrap — a normal state, not an error; the
+   * first Start bootstraps it).
+   */
+  async getAutonomousStatus(
+    repositoryPath: string,
+  ): Promise<IssueFixAutonomousStatusResponse | null> {
     const request = { repositoryPath };
     try {
       return await api.invoke('issue_fix_autonomous_status', { request });
@@ -118,9 +125,10 @@ class IssueFixAPI {
   /**
    * Background-poll variant of `getAutonomousStatus`: projects issue todos and
    * open gates from LoopX's todo list only, so an interval poll never invokes
-   * `quota should-run` (which appends a LoopX rollout event per call).
+   * `quota should-run` (which appends a LoopX rollout event per call). Null
+   * before the repository is bootstrapped.
    */
-  async pollAutonomous(repositoryPath: string): Promise<IssueFixAutonomousPollResponse> {
+  async pollAutonomous(repositoryPath: string): Promise<IssueFixAutonomousPollResponse | null> {
     const request = { repositoryPath };
     try {
       return await api.invoke('issue_fix_autonomous_poll', { request });

src/web-ui/src/infrastructure/api/service-api/IssueFixAPI.ts

@@ -60,7 +60,8 @@
       "closeIssue": "Resolved — approve closing Issue #{{issue}}",
       "closeIssueByPr": "Issue #{{issue}} resolved by PR #{{pr}} — approve closing it",
       "postComment": "Reply drafted for Issue #{{issue}} — approve posting it"
-    }
+    },
+    "notConnected": "Not connected yet — select issues and press Start to begin"
   },
   "status": {
     "queued": "Queued",

src/web-ui/src/locales/en-US/panels/issue-fix.json

@@ -60,7 +60,8 @@
       "closeIssue": "已解决，请批准关闭 Issue #{{issue}}",
       "closeIssueByPr": "Issue #{{issue}} 已由 PR #{{pr}} 修复，请批准关闭",
       "postComment": "已为 Issue #{{issue}} 草拟回复，请批准发布"
-    }
+    },
+    "notConnected": "尚未连接——勾选 Issue 后点击启动即可开始"
   },
   "status": {
     "queued": "排队中",

src/web-ui/src/locales/zh-CN/panels/issue-fix.json

@@ -60,7 +60,8 @@
       "closeIssue": "已解決，請批准關閉 Issue #{{issue}}",
       "closeIssueByPr": "Issue #{{issue}} 已由 PR #{{pr}} 修復，請批准關閉",
       "postComment": "已為 Issue #{{issue}} 草擬回覆，請批准發布"
-    }
+    },
+    "notConnected": "尚未連接——勾選 Issue 後點擊啟動即可開始"
   },
   "status": {
     "queued": "排隊中",