car-runtime 0.42.0 → 0.44.0

package/index.d.ts

@@ -34,6 +34,33 @@
  */
 
 /** Persistent runtime instance with state, memory, tools, and policies. */
+/**
+ * Optional settings for `coderStart`. Every field is independently omittable;
+ * each falls back to the daemon's `~/.car/coder.toml`.
+ *
+ * **Breaking (v0.44.0):** replaced five trailing positional optionals — three
+ * of them numbers — which callers could silently mis-order.
+ */
+export interface CoderStartOptions {
+  /** `"auto" | "native" | "external[:agent_id]" | "foreman[:agent_id]"`. */
+  engine?: string | undefined | null;
+  /** Contract-evaluation rounds before the native loop gives up. */
+  maxIterations?: number | undefined | null;
+  /** Per-session backbone pin, reaching whichever engine runs. */
+  model?: string | undefined | null;
+  /**
+   * External-engine hypothesis budget: fresh repair invocations after a red
+   * pass. Recurrence escalation needs >= 2 to reach the model at all.
+   */
+  repairInvokes?: number | undefined | null;
+  /**
+   * External-engine availability budget: re-invocations after the CLI process
+   * died mid-run. Separate from `repairInvokes` on purpose — one buys a
+   * hypothesis, the other buys a retry.
+   */
+  transientRetries?: number | undefined | null;
+}
+
 export class CarRuntime {
   constructor();
 
@@ -845,9 +872,7 @@ export class CarRuntime {
   coderStart(
     repo: string,
     intent: string,
-    engine?: string | undefined | null,
-    maxIterations?: number | undefined | null,
-    model?: string | undefined | null,
+    options?: CoderStartOptions | undefined | null,
   ): Promise<string>;
 
   /**
@@ -3266,9 +3291,27 @@ export function agentsTailLog(id: string, n?: number | null, stream?: string | n
  * installed AND ready to use" answer. Returns JSON
  * `[ExternalAgentSpec]` (empty array when nothing installed).
  *
+ * `ExternalAgentSpec.execution` (car#746) is the authoritative answer to
+ * "can this binary run at all":
+ *     { state: "runnable" }
+ *   | { state: "unusable", reason: string, checked_at: number }
+ * Written by detection, never revised by a health refresh. `health`
+ * answers a different question (is it authenticated) and is owned by
+ * refreshers that may rewrite it. Prefer `execution` over
+ * `health.status === "not_executable"`, which is still emitted for one
+ * compatibility window. An absent `execution` reads as "runnable".
+ *
  * `ExternalAgentSpec.health` shape (when populated):
  *   { id, status, details, reason?, checked_at }
- *   status: "ready" | "not_configured" | "expired" | "network_error" | "unknown"
+ *   status: "ready" | "not_configured" | "expired" | "network_error"
+ *         | "not_executable" | "unknown"
+ *
+ * `health` is also populated **without** `includeHealth` in one case:
+ * when detection finds the binary but proves it cannot be executed,
+ * the spec comes back with `status: "not_executable"` and a `reason`
+ * naming the path. Do not invoke a spec in that state — it will be
+ * killed at exec. Typical cause on macOS is Gatekeeper quarantine on
+ * a binary installed outside the App Store.
  *
  * The `auth_kind` field is **deprecated** (Phase 2 stage 1) — modern
  * builds keep credentials in OS keystores so the heuristic falls
@@ -3303,11 +3346,16 @@ export function agentsDetectExternal(
  *   {
  *     "id": "claude-code" | "codex" | "gemini",
  *     "status": "ready" | "not_configured" | "expired" |
- *               "network_error" | "unknown",
+ *               "network_error" | "not_executable" | "unknown",
  *     "details": <tool-specific JSON object>,
  *     "reason": <human-readable string when not Ready>,
  *     "checked_at": <unix-secs>
  *   }
+ *
+ * `not_executable` is set by *detection*, not by an auth-status
+ * command — a binary the OS won't run can't report its own auth
+ * state. It means the install is broken, not that the user is signed
+ * out, so don't prompt for a login flow.
  */
 export function agentsHealthExternal(
   id?: string | null,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "car-runtime",
-  "version": "0.42.0",
+  "version": "0.44.0",
   "description": "Common Agent Runtime — a deterministic execution layer for AI agents",
   "main": "index.js",
   "types": "index.d.ts",