KiCad - the KiCad Bridge

@@ -7,7 +7,7 @@ //! `_VERB_CATALOG` plus the autoroute entry from docs/rust-port-plan.md.  use std::path::PathBuf;-use std::time::Duration;+use std::time::{Duration, Instant};  use serde_json::{json, Value}; @@ -101,11 +101,11 @@ pub static VERBS: &[Verb] = &[         name: "kicad_autoroute",         summary: "Route a board with the engine the USER picked: \"ai\" (recommended) returns the plan request you drive with kicad_route_net; \"freerouting\" runs Freerouting headless (installed on demand) and lands its copper live as one undo step per net, or into the closed file.",         mechanism: Mechanism::Ipc, risk: "write", timeout_sec: 900,-        input: "{\"engine\": \"ai\" | \"freerouting\", \"filePath\": \"C:/.../x.kicad_pcb\", \"nets\"?: [\"GND\", ...], \"dryRun\"?: bool, \"passes\"?: 20, \"threads\"?: n, \"timeoutSec\"?: 600, \"apply\"?: \"file\" | \"ipc\", \"backup\"?: true}",+        input: "{\"engine\": \"ai\" | \"freerouting\", \"filePath\": \"C:/.../x.kicad_pcb\", \"nets\"?: [\"GND\", ...], \"dryRun\"?: bool, \"passes\"?: 20, \"threads\"?: n, \"timeoutSec\"?: 600, \"apply\"?: \"file\" | \"ipc\", \"backup\"?: true, \"job\"?: true | \"<id>\"}",         example: "kicad_autoroute {\"engine\":\"ai\",\"filePath\":\"C:/Users/john/proj/board.kicad_pcb\"}",-        hint: "ASK THE USER WHICH ENGINE THEY WANT BEFORE ROUTING and name both every time. ai (recommended): any capable model can drive kicad_route_net (GPT-6 Astra in Codex has routed a 94-footprint board to zero unconnected items this way, Claude Fable 5.1 can, newer models will); the routing verbs give it pads, nets, zones, a live revision, one native undo step per trace and DRC per step, so it honours the schematic's intent and can explain every trace. freerouting: deterministic, installed on demand (88 MB download, bundled Java, no elevation), kicad_freerouting {\"action\":\"status\"} says whether it is present; not installed answers freerouting_not_installed with the install call, and you ask the user before installing. Report which engine produced the copper.",+        hint: "ASK THE USER WHICH ENGINE THEY WANT BEFORE ROUTING and name both every time. ai (recommended): any capable model can drive kicad_route_net (GPT-6 Astra in Codex has routed a 94-footprint board to zero unconnected items this way, Claude Fable 5.1 can, newer models will); the routing verbs give it pads, nets, zones, a live revision, one native undo step per trace and DRC per step, so it honours the schematic's intent and can explain every trace. freerouting: deterministic, installed on demand (88 MB download, bundled Java, no elevation), kicad_freerouting {\"action\":\"status\"} says whether it is present; not installed answers freerouting_not_installed with the install call, and you ask the user before installing. Report which engine produced the copper. Over the relay use job:true and poll; the relay times out around 130 s while the bridge keeps working, and the result of a timed-out synchronous call is not retrievable: kicad_autoroute {\"engine\":\"freerouting\",\"job\":true} answers at once with a job id, kicad_autoroute {\"job\":\"<id>\"} reports running (stepLabel, percent), done (the full routing reply) or failed, kept for an hour. A direct caller may still wait synchronously (timeout 900 s).",         related: &["kicad_freerouting", "kicad_routing_state", "kicad_route_net", "kicad_routing_validate", "kicad_board_pads"],-        pitfalls: &["Never pick the engine for the user; the hint makes you ask (same pattern as foregroundReason).", "engine ai mutates nothing by itself: the copper lands through kicad_route_net calls you make afterwards.", "engine freerouting never installs anything by itself: freerouting_not_installed means ask, then kicad_freerouting {\"action\":\"install\"}, then call again.", "engine freerouting applies live (apply ipc: the board open in the PCB editor with the IPC API on, one native undo step per net named Freerouting <net>) or to the closed file (apply file, .adom-bak beside it); auto picks ipc when the board is open, file otherwise.", "Oval, roundrect and custom pads reach the router as their bounding rect (conservative); dsn.approximatedPads lists them."],+        pitfalls: &["Never pick the engine for the user; the hint makes you ask (same pattern as foregroundReason).", "engine ai mutates nothing by itself: the copper lands through kicad_route_net calls you make afterwards.", "engine freerouting never installs anything by itself: freerouting_not_installed means ask, then kicad_freerouting {\"action\":\"install\"}, then call again.", "engine freerouting applies live (apply ipc: the board open in the PCB editor with the IPC API on, one native undo step per net named Freerouting <net>) or to the closed file (apply file, .adom-bak beside it); auto picks ipc when the board is open, file otherwise.", "Oval, roundrect and custom pads reach the router as their bounding rect (conservative); dsn.approximatedPads lists them.", "Over the relay use job:true and poll; the relay times out around 130 s while the bridge keeps working, and the result of a timed-out synchronous call is not retrievable. A real board takes minutes (a 59-net four-layer board: 40 passes), so job:true is the default choice over ab.", "One autoroute job per board at a time: job_busy names the running id, poll it to completion (or failure) before starting another. The poll takes no engine; a finished job answers for an hour, then job_not_found."],     },     Verb {         name: "kicad_freerouting",@@ -482,7 +482,28 @@ fn engines() -> Value {     ]) } +/// How `job` was given: absent or false (synchronous), `true` (start a background job) or+/// a non-empty id (poll that job). Dispatch asks too: a job start and a poll never touch+/// the editor, so they run without GUI_LOCK.+pub enum JobMode {+    Sync,+    Start,+    Poll(String),+}++pub fn job_mode(args: &Value) -> JobMode {+    match args.get("job") {+        Some(Value::Bool(true)) => JobMode::Start,+        Some(Value::String(s)) if !s.trim().is_empty() => JobMode::Poll(s.trim().to_string()),+        _ => JobMode::Sync,+    }+}+ fn autoroute(state: &mut State, args: &Value) -> Value {+    let mode = job_mode(args);+    if let JobMode::Poll(id) = &mode {+        return autoroute_job_poll(id);+    }     let engine = arg_str(args, "engine").map(|s| s.trim().to_ascii_lowercase());     let dry_run = args.get("dryRun") == Some(&json!(true));     match engine.as_deref() {@@ -493,7 +514,10 @@ fn autoroute(state: &mut State, args: &Value) -> Value {             v         }         Some("ai") => autoroute_ai(state, args, dry_run),-        Some("freerouting") => autoroute_freerouting(state, args, dry_run),+        Some("freerouting") => match mode {+            JobMode::Start => autoroute_job_start(args, dry_run),+            _ => autoroute_freerouting(state, args, dry_run),+        },         Some(other) => {             let mut v = fail("unknown_engine", format!("unknown engine '{other}'"), format!("engine is \"ai\" (recommended) or \"freerouting\". {ASK_BOTH}"));             v["engines"] = engines();@@ -590,19 +614,33 @@ fn autoroute_ai(state: &mut State, args: &Value, dry_run: bool) -> Value { // ---------------------------------------------------------------------------  /// A live progress frame for the caller; ends when dropped (every early return included).+/// A frame that belongs to a background job mirrors every step into the job table too, so+/// the poll and `kicad_status.operations` show the same label and percent. struct Phase {     phase: &'static str,     caller: String,+    job: Option<String>, }  impl Phase {     fn begin(phase: &'static str, label: &str) -> Phase {-        let caller = progress::caller_name();+        Phase::begin_as(phase, label, progress::caller_name(), None)+    }+    /// The caller is captured by whoever starts the frame: the ab caller identity is+    /// process-wide, so a job thread must not read it later (another request may have+    /// replaced it by then).+    fn begin_as(phase: &'static str, label: &str, caller: String, job: Option<String>) -> Phase {         progress::begin_phase(phase, "warm", label, &caller);-        Phase { phase, caller }+        if let Some(id) = &job {+            jobs().step(id, label, None);+        }+        Phase { phase, caller, job }     }     fn step(&self, label: &str, percent: Option<i64>) {         progress::step_for(&self.caller, self.phase, label, percent, None);+        if let Some(id) = &self.job {+            jobs().step(id, label, percent);+        }     } } @@ -701,15 +739,28 @@ fn norm_path(p: &std::path::Path) -> String {     p.to_string_lossy().replace('\\', "/") } -/// Engine `freerouting`: board -> DSN -> Freerouting -> SES -> copper applied live (one-/// undo step per net) or into the closed file, then DRC. Not installed: the install call-/// and a hint that says ask the user; nothing is downloaded here.-fn autoroute_freerouting(state: &mut State, args: &Value, dry_run: bool) -> Value {+/// Everything `engine: freerouting` checks before any work. One function for the+/// synchronous call and the background job, so `job:true` refuses with exactly the errors+/// the synchronous call would (not installed, bad apply, board open, no ipc feature).+struct Prepared {+    exe: PathBuf,+    passes: u32,+    threads: Option<u32>,+    timeout_sec: u64,+    wanted: Option<Vec<String>>,+    loaded: pcb::Loaded,+    use_ipc: bool,+    live_args: Value,+    backup: bool,+    dry_run: bool,+}++fn freerouting_prepare(args: &Value, dry_run: bool) -> Result<Prepared, Value> {     let status = freerouting::status();     let Some(exe) = status.exe.clone() else {         let mut v = freerouting::not_installed(&status);         v["engines"] = engines();-        return v;+        return Err(v);     };     let passes = args.get("passes").and_then(Value::as_u64).map(|p| p.clamp(1, 999) as u32).unwrap_or(freerouting::DEFAULT_PASSES);     let threads = args.get("threads").and_then(Value::as_u64).map(|t| t.clamp(1, 64) as u32);@@ -718,13 +769,10 @@ fn autoroute_freerouting(state: &mut State, args: &Value, dry_run: bool) -> Valu     let apply_arg = arg_str(args, "apply").map(|s| s.trim().to_ascii_lowercase());     if let Some(a) = &apply_arg {         if a != "file" && a != "ipc" {-            return fail("bad_apply", format!("apply must be \"file\" or \"ipc\", not '{a}'"), "apply file writes the closed board with a backup; apply ipc commits live into the open PCB editor. Omit it and the bridge picks ipc when the board is open, file otherwise.");+            return Err(fail("bad_apply", format!("apply must be \"file\" or \"ipc\", not '{a}'"), "apply file writes the closed board with a backup; apply ipc commits live into the open PCB editor. Omit it and the bridge picks ipc when the board is open, file otherwise."));         }     }-    let loaded = match pcb::load(args, true) {-        Ok(l) => l,-        Err(e) => return e,-    };+    let loaded = pcb::load(args, true)?;     let board_open = pcb::lock_file(&loaded.path).is_some();     let use_ipc = match apply_arg.as_deref() {         Some("ipc") => true,@@ -732,16 +780,15 @@ fn autoroute_freerouting(state: &mut State, args: &Value, dry_run: bool) -> Valu         _ => board_open,     };     if !use_ipc && board_open {-        return json!({+        return Err(json!({             "success": false, "errorCode": "board_open", "engine": "freerouting", "mutated": false,             "error": "This board is open in KiCad; apply:\"file\" would conflict with the editor",             "_hint": "Let the bridge apply live instead (omit apply, or apply:\"ipc\": the PCB editor with the IPC API on takes the copper as one undo step per net), or close the board for a file apply.",-        });+        }));     }     if use_ipc && !ipc_available() {-        return fail("ipc_unavailable", "This build has the ipc feature off; a live apply needs the KiCad IPC client compiled in", "Close the board and call again with apply:\"file\", or use a build with the ipc feature.");+        return Err(fail("ipc_unavailable", "This build has the ipc feature off; a live apply needs the KiCad IPC client compiled in", "Close the board and call again with apply:\"file\", or use a build with the ipc feature."));     }-    let phase = Phase::begin("autoroute", "reading the board");     // The board the router sees: the editor's own serialisation when applying live (unsaved     // edits included), the file otherwise.     let mut live_args = json!({"filePath": loaded.path.to_string_lossy()});@@ -750,8 +797,50 @@ fn autoroute_freerouting(state: &mut State, args: &Value, dry_run: bool) -> Valu             live_args[k] = v.clone();         }     }+    Ok(Prepared { exe, passes, threads, timeout_sec, wanted, loaded, use_ipc, live_args, backup: backup_wanted(args), dry_run })+}++/// Engine `freerouting`, synchronous: board -> DSN -> Freerouting -> SES -> copper applied+/// live (one undo step per net) or into the closed file, then DRC. Not installed: the+/// install call and a hint that says ask the user; nothing is downloaded here. Dispatch+/// holds GUI_LOCK for the whole call (Mechanism::Ipc); a direct caller may wait the 900 s,+/// the ab relay gives up around 130 s and the reply is then lost, which is what `job:true`+/// is for.+fn autoroute_freerouting(state: &mut State, args: &Value, dry_run: bool) -> Value {+    let prep = match freerouting_prepare(args, dry_run) {+        Ok(p) => p,+        Err(e) => return e,+    };+    let key = job_board_key(&prep.loaded.path);+    {+        let mut t = jobs();+        t.expire(Instant::now());+        if let Some(busy) = t.busy_reply(&key, Instant::now()) {+            return busy;+        }+    }+    let phase = Phase::begin("autoroute", "reading the board");+    freerouting_execute(state, prep, &phase, false)+}++/// GUI_LOCK for the sections of a job thread that talk to the editor. The synchronous+/// call passes `own = false`: dispatch already holds the lock and std's Mutex is not+/// reentrant.+fn gui_guard(own: bool) -> Option<std::sync::MutexGuard<'static, ()>> {+    own.then(|| GUI_LOCK.lock().unwrap_or_else(|e| e.into_inner()))+}++/// The work itself, shared by the synchronous call and the job thread. A job thread takes+/// GUI_LOCK only around the editor sections (live snapshot, live commit, live DRC) and+/// holds nothing while Freerouting runs for minutes, so window verbs, status polls and the+/// job poll are never queued behind a routing pass.+fn freerouting_execute(state: &mut State, prep: Prepared, phase: &Phase, own_gui_lock: bool) -> Value {+    let Prepared { exe, passes, threads, timeout_sec, wanted, loaded, use_ipc, live_args, backup, dry_run } = prep;     let (text, board, mut revision): (String, pcb::Board, Option<String>) = if use_ipc {-        match live_snapshot(state, &live_args) {+        let gui = gui_guard(own_gui_lock);+        let snap = live_snapshot(state, &live_args);+        drop(gui);+        match snap {             Ok((t, b, r)) => (t, b, Some(r)),             Err(e) => return e,         }@@ -863,10 +952,12 @@ fn autoroute_freerouting(state: &mut State, args: &Value, dry_run: bool) -> Valu     // ---- apply     let apply_result = if use_ipc {         phase.step(&format!("committing {} net(s) live", copper.len()), Some(90));-        commit_live(state, &live_args, &copper, revision.take().unwrap_or_default())+        let gui = gui_guard(own_gui_lock);+        let r = commit_live(state, &live_args, &copper, revision.take().unwrap_or_default());+        drop(gui);+        r     } else {         phase.step("writing the board file", Some(90));-        let backup = backup_wanted(args);         match freerouting::apply_to_file(&loaded, &copper, backup) {             Ok((bak, s, v)) => Ok(json!({"applied": "file", "backup": bak, "segments": s, "vias": v, "reloaded": false, "source": "file"})),             Err(e) => Err(e),@@ -897,7 +988,9 @@ fn autoroute_freerouting(state: &mut State, args: &Value, dry_run: bool) -> Valu     phase.step("DRC", Some(95));     let kicad_cli = state.kicad_info().primary().map(|p| PathBuf::from(&p.kicad_cli)).filter(|p| p.is_file());     response["drc"] = if use_ipc {+        let gui = gui_guard(own_gui_lock);         let v = live(state, &live_args, Live::Validate);+        drop(gui);         if v["success"] == json!(true) {             json!({"available": true, "source": "live-editor-snapshot", "errors": v["errors"], "warnings": v["warnings"], "unconnected": v["unconnected"], "clean": v["clean"], "summary": v["summary"], "revision": v["revision"]})         } else {@@ -916,6 +1009,228 @@ fn autoroute_freerouting(state: &mut State, args: &Value, dry_run: bool) -> Valu     response } +// ---------------------------------------------------------------------------+// Background autoroute jobs+// ---------------------------------------------------------------------------+//+// A real board takes minutes (a 59-net four-layer ESC: 40 passes over several minutes);+// the ab relay gives up around 130 s and the reply of a timed-out synchronous call is+// gone even though the bridge finished the work. `job:true` validates like the+// synchronous call, then runs the same work on its own thread and parks the full reply+// here, keyed by id, for an hour after it finishes. The thread reports through `Phase`,+// so the live frame in the progress registry (`kicad_status.operations`) and this table+// carry the same label and percent.++/// How long a finished job stays pollable.+const JOB_KEEP: Duration = Duration::from_secs(3600);++struct AutorouteJob {+    id: String,+    /// Normalised, lower-cased board path: the one-job-per-board key.+    board_key: String,+    board_path: String,+    engine: String,+    caller: String,+    started: Instant,+    started_at: f64,+    phase: String,+    step_label: String,+    percent: Option<i64>,+    result: Option<Value>,+    finished: Option<Instant>,+}++struct JobTable {+    jobs: Vec<AutorouteJob>,+    seq: u64,+}++static AUTOROUTE_JOBS: std::sync::Mutex<JobTable> = std::sync::Mutex::new(JobTable { jobs: Vec::new(), seq: 0 });++fn jobs() -> std::sync::MutexGuard<'static, JobTable> {+    AUTOROUTE_JOBS.lock().unwrap_or_else(|e| e.into_inner())+}++fn job_board_key(p: &std::path::Path) -> String {+    norm_path(p).to_ascii_lowercase()+}++fn epoch_now() -> f64 {+    std::time::SystemTime::now().duration_since(std::time::UNIX_EPOCH).map(|d| d.as_secs_f64()).unwrap_or(0.0)+}++impl JobTable {+    /// Drop finished jobs older than JOB_KEEP. A running job never expires.+    fn expire(&mut self, now: Instant) {+        self.jobs.retain(|j| match j.finished {+            Some(f) => now.saturating_duration_since(f) < JOB_KEEP,+            None => true,+        });+    }++    fn get(&self, id: &str) -> Option<&AutorouteJob> {+        self.jobs.iter().find(|j| j.id == id)+    }++    fn running_for(&self, board_key: &str) -> Option<&AutorouteJob> {+        self.jobs.iter().find(|j| j.board_key == board_key && j.result.is_none())+    }++    /// Register a new job, or Err(the running job's id) when the board already has one.+    fn start(&mut self, board_key: &str, board_path: &str, engine: &str, caller: &str, now: Instant) -> Result<String, String> {+        if let Some(j) = self.running_for(board_key) {+            return Err(j.id.clone());+        }+        self.seq += 1;+        let suffix: String = kicad_core::schematic::new_uuid().chars().take(8).collect();+        let id = format!("autoroute-{}-{suffix}", self.seq);+        self.jobs.push(AutorouteJob {+            id: id.clone(),+            board_key: board_key.to_string(),+            board_path: board_path.to_string(),+            engine: engine.to_string(),+            caller: caller.to_string(),+            started: now,+            started_at: epoch_now(),+            phase: "autoroute".into(),+            step_label: "starting".into(),+            percent: Some(0),+            result: None,+            finished: None,+        });+        Ok(id)+    }++    /// Mirror of `progress::step_for`: the label replaces, the percent never goes backwards.+    fn step(&mut self, id: &str, label: &str, percent: Option<i64>) {+        if let Some(j) = self.jobs.iter_mut().find(|j| j.id == id && j.result.is_none()) {+            j.step_label = label.to_string();+            if let Some(p) = percent {+                j.percent = Some(p.max(j.percent.unwrap_or(0)));+            }+        }+    }++    /// Park the verb's full reply (success or error) and start the one-hour clock.+    fn complete(&mut self, id: &str, result: Value, now: Instant) {+        if let Some(j) = self.jobs.iter_mut().find(|j| j.id == id) {+            let ok = result.get("success") != Some(&json!(false));+            j.step_label = if ok { "done".into() } else { result.get("error").and_then(Value::as_str).unwrap_or("failed").chars().take(80).collect() };+            j.percent = Some(100);+            j.result = Some(result);+            j.finished = Some(now);+        }+    }++    /// The poll reply: `running` with the live frame, or the parked reply with `status`+    /// done or failed merged in.+    fn snapshot(&self, id: &str, now: Instant) -> Option<Value> {+        let j = self.get(id)?;+        let elapsed = j.finished.unwrap_or(now).saturating_duration_since(j.started).as_secs_f64().round();+        Some(match &j.result {+            None => json!({+                "success": true, "status": "running", "job": j.id, "engine": j.engine, "boardPath": j.board_path,+                "phase": j.phase, "stepLabel": j.step_label, "percent": j.percent,+                "elapsedSec": elapsed, "startedAt": j.started_at, "caller": j.caller,+                "statusVerb": "kicad_autoroute", "statusArgs": {"job": j.id},+                "_hint": "Still routing: poll again in 10 to 20 s. stepLabel and percent are the same frame kicad_status.operations shows. Nothing to report to the user yet beyond the pass count.",+            }),+            Some(r) => {+                let ok = r.get("success") != Some(&json!(false));+                let mut v = r.clone();+                v["status"] = json!(if ok { "done" } else { "failed" });+                v["job"] = json!(j.id);+                v["engine"] = json!(j.engine);+                v["boardPath"] = json!(j.board_path);+                v["jobElapsedSec"] = json!(elapsed);+                v["startedAt"] = json!(j.started_at);+                v["finishedAgoSec"] = json!(j.finished.map(|f| now.saturating_duration_since(f).as_secs_f64().round()));+                v["keptForSec"] = json!(JOB_KEEP.as_secs());+                v+            }+        })+    }++    /// `job_busy` for a board that already has a running job, else None.+    fn busy_reply(&self, board_key: &str, now: Instant) -> Option<Value> {+        let j = self.running_for(board_key)?;+        let mut v = fail("job_busy", format!("an autoroute job is already running on this board: {}", j.id), format!("One autoroute job per board at a time. Poll kicad_autoroute {{\"job\":\"{}\"}} until its status is done or failed, then call again.", j.id));+        v["job"] = json!(j.id);+        v["status"] = json!("running");+        v["engine"] = json!(j.engine);+        v["boardPath"] = json!(j.board_path);+        v["stepLabel"] = json!(j.step_label);+        v["percent"] = json!(j.percent);+        v["elapsedSec"] = json!(now.saturating_duration_since(j.started).as_secs_f64().round());+        v["mutated"] = json!(false);+        Some(v)+    }++    fn ids(&self) -> Value {+        json!(self.jobs.iter().map(|j| json!({"job": j.id, "status": match &j.result { None => "running", Some(r) if r.get("success") != Some(&json!(false)) => "done", Some(_) => "failed" }, "boardPath": j.board_path})).collect::<Vec<_>>())+    }+}++/// `job:true`: validate exactly like the synchronous call, register the job, run the+/// work on its own thread, answer at once with the id to poll.+fn autoroute_job_start(args: &Value, dry_run: bool) -> Value {+    let prep = match freerouting_prepare(args, dry_run) {+        Ok(p) => p,+        Err(e) => return e,+    };+    let board_path = norm_path(&prep.loaded.path);+    let key = job_board_key(&prep.loaded.path);+    let apply = if prep.use_ipc { "ipc" } else { "file" };+    let caller = progress::caller_name();+    let id = {+        let mut t = jobs();+        let now = Instant::now();+        t.expire(now);+        match t.start(&key, &board_path, "freerouting", &caller, now) {+            Ok(id) => id,+            Err(_) => return t.busy_reply(&key, now).unwrap_or_else(|| fail("job_busy", "an autoroute job is already running on this board", "Poll it, then call again.")),+        }+    };+    let thread_id = id.clone();+    let spawned = std::thread::Builder::new().name(format!("kicad-{id}")).spawn(move || {+        let phase = Phase::begin_as("autoroute", "reading the board", caller, Some(thread_id.clone()));+        let out = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {+            let mut state = State::new();+            freerouting_execute(&mut state, prep, &phase, true)+        }))+        .unwrap_or_else(|_| fail("handler_panicked", "the autoroute job thread panicked", "Read kicad_log_tail for the panic; the board may be partly routed (each committed net is its own undo step)."));+        drop(phase);+        jobs().complete(&thread_id, out, Instant::now());+    });+    if let Err(e) = spawned {+        let err = fail("spawn_failed", format!("could not start the autoroute thread: {e}"), "Call again without job:true, or retry.");+        jobs().complete(&id, err.clone(), Instant::now());+        return err;+    }+    json!({+        "success": true, "status": "ok", "job": id, "engine": "freerouting", "started": true,+        "boardPath": board_path, "apply": apply, "dryRun": dry_run, "mutated": false, "phase": "autoroute",+        "statusVerb": "kicad_autoroute", "statusArgs": {"job": id},+        "_hint": format!("Routing runs in the background. Poll kicad_autoroute {{\"job\":\"{id}\"}} every 10 to 20 s: status running carries stepLabel and percent (kicad_status.operations shows the same frame); status done carries the full routing reply (routed, applied, drc, freerouting, dsn, revision, undoSteps, itemIds); status failed carries the error reply. The result is kept for an hour after the job finishes."),+    })+}++/// `job:"<id>"`: the job's state.+fn autoroute_job_poll(id: &str) -> Value {+    let mut t = jobs();+    let now = Instant::now();+    t.expire(now);+    match t.snapshot(id, now) {+        Some(v) => v,+        None => {+            let mut v = fail("job_not_found", format!("no autoroute job '{id}'"), "Job ids come from kicad_autoroute {\"engine\":\"freerouting\",\"job\":true}; a finished job is kept for an hour, then its result is gone. `jobs` lists what the bridge still holds.");+            v["job"] = json!(id);+            v["jobs"] = t.ids();+            v+        }+    }+}+ #[cfg(feature = "ipc")] fn live_snapshot(state: &mut State, live_args: &Value) -> Result<(String, pcb::Board, String), Value> {     use kicad_core::{detect, ipc};@@ -977,3 +1292,137 @@ fn commit_live(state: &mut State, live_args: &Value, copper: &[dsn::NetCopper], fn commit_live(_state: &mut State, _live_args: &Value, _copper: &[dsn::NetCopper], _revision: String) -> Result<Value, Value> {     Err(fail("ipc_unavailable", "ipc feature off in this build", "Close the board and apply to the file.")) }+++#[cfg(test)]+mod tests {+    use super::*;++    fn table() -> JobTable {+        JobTable { jobs: Vec::new(), seq: 0 }+    }++    #[test]+    fn job_insert_and_poll_running() {+        let mut t = table();+        let now = Instant::now();+        let id = t.start("c:/x/board.kicad_pcb", "C:/x/board.kicad_pcb", "freerouting", "thread-1", now).unwrap();+        assert!(id.starts_with("autoroute-1-"));+        let v = t.snapshot(&id, now).unwrap();+        assert_eq!(v["status"], json!("running"));+        assert_eq!(v["success"], json!(true));+        assert_eq!(v["job"], json!(id));+        assert_eq!(v["engine"], json!("freerouting"));+        assert_eq!(v["boardPath"], json!("C:/x/board.kicad_pcb"));+        assert_eq!(v["phase"], json!("autoroute"));+        assert_eq!(v["stepLabel"], json!("starting"));+        assert_eq!(v["percent"], json!(0));+        assert_eq!(v["caller"], json!("thread-1"));+        assert_eq!(v["statusArgs"], json!({"job": id}));+        // Steps mirror the registry contract: label replaces, percent never goes backwards.+        t.step(&id, "Freerouting pass 3 of up to 20", Some(18));+        t.step(&id, "Freerouting pass 3 of up to 20 (again)", Some(10));+        let v = t.snapshot(&id, now + Duration::from_secs(42)).unwrap();+        assert_eq!(v["stepLabel"], json!("Freerouting pass 3 of up to 20 (again)"));+        assert_eq!(v["percent"], json!(18));+        assert_eq!(v["elapsedSec"], json!(42.0));+        assert!(t.snapshot("autoroute-9-nope", now).is_none());+    }++    #[test]+    fn job_complete_done_and_failed() {+        let mut t = table();+        let t0 = Instant::now();+        let id = t.start("c:/x/a.kicad_pcb", "C:/x/a.kicad_pcb", "freerouting", "th", t0).unwrap();+        let reply = json!({"success": true, "engine": "freerouting", "mutated": true, "routed": {"netCount": 59}, "applied": "ipc", "drc": {"clean": true}, "freerouting": {"passes": 40}, "dsn": {"stats": {}}, "revision": "abc", "undoSteps": 59, "itemIds": 812, "_hint": "Freerouting routed 59 net(s)"});+        t.complete(&id, reply, t0 + Duration::from_secs(300));+        // A step after completion changes nothing.+        t.step(&id, "late", Some(1));+        let v = t.snapshot(&id, t0 + Duration::from_secs(360)).unwrap();+        assert_eq!(v["status"], json!("done"));+        assert_eq!(v["success"], json!(true));+        assert_eq!(v["job"], json!(id));+        for k in ["routed", "applied", "drc", "freerouting", "dsn", "revision", "undoSteps", "itemIds", "_hint", "mutated"] {+            assert!(v.get(k).is_some(), "done reply keeps {k}");+        }+        assert_eq!(v["undoSteps"], json!(59));+        assert_eq!(v["jobElapsedSec"], json!(300.0));+        assert_eq!(v["finishedAgoSec"], json!(60.0));+        assert_eq!(v["keptForSec"], json!(3600));+        assert_eq!(t.get(&id).unwrap().step_label, "done");+        assert_eq!(t.get(&id).unwrap().percent, Some(100));++        let id2 = t.start("c:/x/b.kicad_pcb", "C:/x/b.kicad_pcb", "freerouting", "th", t0).unwrap();+        t.complete(&id2, fail("freerouting_timeout", "Freerouting did not finish within 600 s", "Raise timeoutSec"), t0 + Duration::from_secs(600));+        let v = t.snapshot(&id2, t0 + Duration::from_secs(601)).unwrap();+        assert_eq!(v["status"], json!("failed"));+        assert_eq!(v["success"], json!(false));+        assert_eq!(v["errorCode"], json!("freerouting_timeout"));+        assert_eq!(v["job"], json!(id2));+        assert_eq!(t.get(&id2).unwrap().step_label, "Freerouting did not finish within 600 s");+        let ids = t.ids();+        assert_eq!(ids[0]["status"], json!("done"));+        assert_eq!(ids[1]["status"], json!("failed"));+    }++    #[test]+    fn job_expires_after_an_hour_running_never() {+        let mut t = table();+        let t0 = Instant::now();+        let done = t.start("c:/x/a.kicad_pcb", "C:/x/a.kicad_pcb", "freerouting", "th", t0).unwrap();+        let running = t.start("c:/x/b.kicad_pcb", "C:/x/b.kicad_pcb", "freerouting", "th", t0).unwrap();+        t.complete(&done, json!({"success": true}), t0 + Duration::from_secs(100));+        t.expire(t0 + Duration::from_secs(100) + JOB_KEEP - Duration::from_secs(1));+        assert!(t.get(&done).is_some(), "kept inside the hour");+        t.expire(t0 + Duration::from_secs(100) + JOB_KEEP);+        assert!(t.get(&done).is_none(), "gone after the hour");+        t.expire(t0 + Duration::from_secs(100_000));+        assert!(t.get(&running).is_some(), "a running job never expires");+    }++    #[test]+    fn job_busy_per_board() {+        let mut t = table();+        let t0 = Instant::now();+        let id = t.start("c:/x/a.kicad_pcb", "C:/x/a.kicad_pcb", "freerouting", "th", t0).unwrap();+        t.step(&id, "Freerouting pass 2 of up to 20", Some(13));+        assert_eq!(t.start("c:/x/a.kicad_pcb", "C:/x/a.kicad_pcb", "freerouting", "other", t0), Err(id.clone()));+        let busy = t.busy_reply("c:/x/a.kicad_pcb", t0 + Duration::from_secs(30)).unwrap();+        assert_eq!(busy["success"], json!(false));+        assert_eq!(busy["errorCode"], json!("job_busy"));+        assert_eq!(busy["job"], json!(id));+        assert_eq!(busy["status"], json!("running"));+        assert_eq!(busy["stepLabel"], json!("Freerouting pass 2 of up to 20"));+        assert_eq!(busy["percent"], json!(13));+        assert_eq!(busy["elapsedSec"], json!(30.0));+        assert!(busy["_hint"].as_str().unwrap().contains(&id));+        // Another board is free; the same board is free again once its job finished.+        assert!(t.start("c:/x/b.kicad_pcb", "C:/x/b.kicad_pcb", "freerouting", "th", t0).is_ok());+        assert!(t.busy_reply("c:/y/none.kicad_pcb", t0).is_none());+        t.complete(&id, json!({"success": true}), t0 + Duration::from_secs(60));+        assert!(t.busy_reply("c:/x/a.kicad_pcb", t0).is_none());+        let again = t.start("c:/x/a.kicad_pcb", "C:/x/a.kicad_pcb", "freerouting", "th", t0).unwrap();+        assert_ne!(again, id);+        assert!(again.starts_with("autoroute-3-"));+    }++    #[test]+    fn job_mode_from_args() {+        assert!(matches!(job_mode(&json!({})), JobMode::Sync));+        assert!(matches!(job_mode(&json!({"job": false})), JobMode::Sync));+        assert!(matches!(job_mode(&json!({"job": ""})), JobMode::Sync));+        assert!(matches!(job_mode(&json!({"job": true})), JobMode::Start));+        match job_mode(&json!({"job": " autoroute-1-abcd1234 "})) {+            JobMode::Poll(id) => assert_eq!(id, "autoroute-1-abcd1234"),+            _ => panic!("a non-empty string is a poll"),+        }+    }++    #[test]+    fn poll_unknown_id() {+        let v = autoroute_job_poll("autoroute-0-missing");+        assert_eq!(v["errorCode"], json!("job_not_found"));+        assert_eq!(v["job"], json!("autoroute-0-missing"));+        assert!(v["jobs"].is_array());+    }+}\ No newline at end of file