cueline 0.1.2 → 0.1.3

package/dist/src/version.js

@@ -1,2 +1,2 @@
-export const CUELINE_VERSION = "0.1.2";
+export const CUELINE_VERSION = "0.1.3";
 //# sourceMappingURL=version.js.map

package/docs/compatibility.md

@@ -26,10 +26,12 @@ The v0.1 adapter relies on accessible textbox/button roles and assistant-message
 - text controller observations and commands
 - `dispatch`, `wait`, `inspect`, `complete`, and `blocked`
 - foreground and background local jobs
+- concurrent all-`advise` batches and serialized batches containing `work`
 - deterministic routing before spawn
 - append-only run recovery and atomic snapshots
 - continuation by run ID and stored conversation URL
 - read-only persisted-state loading through `loadCueLineRunState`
+- cross-session run status, runtime ownership, run/job cancellation, and optional run deadlines
 - injected fake browser/runner for offline tests
 
 ## Not supported in v0.1
@@ -46,7 +48,7 @@ The v0.1 adapter relies on accessible textbox/button roles and assistant-message
 
 ## CLI boundary
 
-`cueline doctor`, `routing`, `jobs`, and `config path` diagnose the local installation and state. They do not drive the ChatGPT page. Live orchestration is an imported API run inside Codex so that the IAB browser object can be injected or resolved.
+`cueline doctor`, `routing`, `jobs`, `run status`, `run cancel` / `run stop`, `job cancel`, and `config path` diagnose or control the local runtime state. They do not drive the ChatGPT page. Live orchestration is an imported API run inside Codex so that the IAB browser object can be injected or resolved.
 
 ## Live readiness checklist
 

package/docs/controller-protocol.md

@@ -35,7 +35,7 @@ A stale or mismatched value is rejected. CueLine parses only the **last complete
 }
 ```
 
-Job states are `pending`, `running`, `succeeded`, `failed`, `timed_out`, or `ambiguous`. Before browser submission, a single output/error field is bounded to 40,000 characters and only the most recent 20 notices are sent. The local event log remains the recovery record.
+Job states are `pending`, `running`, `succeeded`, `failed`, `timed_out`, `cancelled`, or `ambiguous`. Before browser submission, a single output/error field is bounded to 40,000 characters and only the most recent 20 notices are sent. The local event log remains the recovery record.
 
 ## Command envelope
 
@@ -81,7 +81,9 @@ Schedules one or more local jobs.
 }
 ```
 
-`job_key` must be unique inside the command and match the supported identifier form. `mode` is `advise` or `work`. Optional fields are `required`, `timeout_ms`, `runner`, `workdir`, and `background`. The local runtime—not ChatGPT—resolves the configured executable. `lane` must be a listed available lane; a runner ID is not a lane name. When `runner` is supplied, it must name an enabled, available candidate in the selected lane. CueLine validates every new route in the dispatch before registering or starting any job. One invalid route rejects the whole command and requests a corrected envelope with the same pending identity. Repeating an already persisted deterministic job is ignored rather than spawned again.
+`job_key` must be unique inside the command and match the supported identifier form. `mode` is `advise` or `work`. Optional fields are `required`, `timeout_ms`, `runner`, `workdir`, and `background`. `runner_id` is invalid and produces an explicit correction to use `runner`. The local runtime—not ChatGPT—resolves the configured executable. `lane` must be a listed available lane; a runner ID is not a lane name. When `runner` is supplied, it must name an enabled, available candidate in the selected lane. CueLine validates every new route in the dispatch before registering or starting any job. One invalid route rejects the whole command and requests a corrected envelope with the same pending identity. Repeating an already persisted deterministic job is ignored rather than spawned again.
+
+If every job in one dispatch is `advise`, CueLine starts them concurrently and then reports all results. If any job is `work`, the entire dispatch remains serial in command order.
 
 ### `wait`
 

package/docs/runner-contract.md

@@ -13,6 +13,8 @@ Every process uses a `RunnerSpec`:
 ```ts
 interface RunnerSpec {
   jobId: string;
+  runId?: string;
+  jobKey?: string;
   argv: readonly string[];
   stdin?: string;
   mode: "advise" | "work";
@@ -22,6 +24,7 @@ interface RunnerSpec {
   task?: string;
   cwd?: string;
   env?: NodeJS.ProcessEnv;
+  signal?: AbortSignal;
 }
 ```
 
@@ -35,6 +38,7 @@ interface RunnerSpec {
 - The effective output is stdout, stderr, or both in that order.
 - Exit code 0 is `succeeded`; a non-zero exit or spawn error is `failed`.
 - At timeout CueLine sends `SIGTERM`, then schedules `SIGKILL` after 250 ms if needed; the result is `timed_out`.
+- Cancellation uses the same owned-process termination path. `advise` becomes `cancelled`; started `work` becomes `ambiguous`.
 - Empty output is explicitly recorded instead of being replaced with invented content.
 - Results are never marked retryable by the process runner.
 
@@ -42,7 +46,9 @@ For an unsuccessful `work` job, `ambiguousSideEffects` is true because CueLine c
 
 ## Foreground and background
 
-A foreground `start` waits for the single execution and persists its terminal status. A background `start` persists and returns `running` immediately while the same completion promise continues. `waitForCompletion(jobId)` returns that completion or the last persisted status.
+A foreground `start` waits for the single execution and persists its terminal status. A background `start` persists and returns `running` immediately while the same completion promise continues. `waitForCompletion(jobId)` returns that completion or the last persisted status. The supervisor persists run ID, job key, lane, mode, and child PID after spawn. PID is observability, not stand-alone cancellation authority.
+
+`cancel(jobId)` and `cancelAll()` operate only on executions owned by the current supervisor. Cross-session CLI cancellation is a durable request consumed by that owner. CueLine does not kill an unverified process merely because a stale status file contains a PID.
 
 The controller loop derives deterministic job IDs from the run, `job_key`, and job specification. A duplicate dispatch already present in run state is recorded as a notice and skipped. This is the run-level at-most-once gate; it is not a distributed transaction across hosts.
 

package/docs/state-and-recovery.md

@@ -9,6 +9,9 @@ ${CUELINE_HOME:-$HOME/.cueline}/
 ├── runs/
 │   └── <run-id>/
 │       ├── events.jsonl
+│       ├── runtime.json
+│       ├── cancel.json                 # only after run cancellation is requested
+│       ├── job-cancellations/          # only after job cancellation is requested
 │       └── snapshot.json
 └── jobs/
     └── <job-id>.json
@@ -26,7 +29,7 @@ Important transitions include:
 - controller turn intent, submission checkpoints, response, reconciliation, rejection, and accepted command
 - job registration and status changes
 - notices
-- complete, blocked, and failed terminal records
+- complete, blocked, cancelled, and failed terminal records
 
 The controller turn is recorded before sending it through the browser. Immediately before the send click, CueLine records `controller_turn_submission_started` with `submission_state: possibly_sent`; after the click it records `controller_turn_submitted`. A verified response is recorded separately. A job is registered only after the entire dispatch has passed pre-spawn route validation, and before its process starts. This ordering leaves evidence when an interruption occurs between intent and side effect.
 
@@ -42,15 +45,26 @@ The snapshot is therefore disposable. Do not edit the event log by hand; invalid
 
 ## Job status
 
-The supervisor atomically replaces one JSON file per job. Foreground work returns its terminal status directly. Background work first persists `running`; later `wait` reads the same in-process completion or the last persisted status.
+The supervisor atomically replaces one JSON file per job. New records include run ID, job key, lane, mode, and spawned child PID. PID is diagnostic evidence only; CueLine never treats a PID alone as authority to kill a process. Foreground work returns its terminal status directly. Background work first persists `running`; later `wait` reads the same in-process completion or the last persisted status.
 
-The run event log still records the controller-visible job transitions. A status file is execution evidence, not a substitute for the run history.
+The run event log still records the controller-visible job transitions. A status file is execution evidence, not a substitute for the run history. `cueline jobs --json` adds a derived observed status: `running` requires active runtime ownership, `orphaned` means the persisted job says running but the owner is not active, and `unverified` covers legacy records without a run ID.
+
+## Runtime ownership and status
+
+`runtime.json` is an owner heartbeat lease. A live controller refreshes it while it owns the run and marks it released on a normal exit. `cueline run status <run-id> --json` combines event replay, lease ownership, cancellation requests, and job state.
+
+- `controller.responseAccepted: true` means a controller response was accepted. `lastAcceptedAction` and `lastAcceptedJobKeys` summarize what that response ordered without dumping its full task text. Do not describe this phase as waiting for ChatGPT.
+- `phase: jobs_running` plus `runtime.ownership: active` means local jobs are executing under the original loop.
+- `runtime_ownership_unknown` or `runtime_stale` means persisted `running` is not proof of a live process. Active-looking jobs are reported as `orphaned`.
+- `runtime_active` means a live owner is still settling a failed state; another session must observe rather than continue.
+- `continueAllowed: false` is a hard stop. Another session must not send, resume, or claim completion.
 
 ## Continue behavior
 
-`continueCueLineRun` loads the exact `runId`, replays state as needed, and resumes the same persisted run. The public runtime also reuses the stored ChatGPT conversation URL unless an explicit compatible adapter is supplied.
+Always run `cueline run status <run-id> --json` before continuation. `continueCueLineRun` loads the exact `runId`, replays state as needed, and resumes the same persisted run. The public runtime also reuses the stored ChatGPT conversation URL unless an explicit compatible adapter is supplied.
 
-- `complete` and `blocked` runs are returned as-is; they are not dispatched again.
+- `complete`, `blocked`, and `cancelled` runs are returned as-is; they are not dispatched again.
+- an active owner is rejected with `RUN_ALREADY_ACTIVE`; missing ownership is rejected with `RUN_OWNERSHIP_UNVERIFIED`; a stale lease requires explicit recovery
 - a non-terminal or locally `failed` run with no pending controller turn can be marked resumed and driven for additional rounds
 - when a failure proves `definitely_not_sent` for the exact sole pending request, CueLine records that turn as abandoned and safely starts a new round
 - a pending controller turn is reconciled read-only from the exact conversation before any new prompt is sent
@@ -59,6 +73,16 @@ The run event log still records the controller-visible job transitions. A status
 - deterministic job IDs suppress a repeated dispatch already present in state
 - running jobs can be observed or waited through their persisted status
 
+All jobs in an accepted dispatch start concurrently only when every job is `advise`. A dispatch containing any `work` job is serialized in command order to avoid overlapping mutations.
+
+## Cancellation and deadlines
+
+`cueline run cancel <run-id>` and its `run stop` alias write a durable request. `cueline job cancel <run-id> <job-id>` targets one job. An active owner observes the request, sends `SIGTERM` to its owned child, escalates to `SIGKILL` after the grace interval, and persists the terminal transition. Cancelled `advise` is `cancelled`; started `work` is `ambiguous` because partial side effects cannot be disproved.
+
+When a legacy run has no verifiable owner, run cancellation closes the run and changes active-looking jobs to `ambiguous`; it does not claim an unknown process was killed. A stale current-generation lease records the request but requires inspection rather than unsafe PID-based killing.
+
+`runTimeoutMs` is an optional run-level deadline. It aborts the controller and owned jobs before returning `RUN_TIMEOUT`. `defaultTimeoutMs` and job `timeout_ms` remain per-job limits. A caller-side or tool-side wait timeout is not a cancellation signal; after one fires, inspect `run status`, then explicitly cancel if required. API callers may pass `signal` for direct cancellation propagation.
+
 For one unambiguous pending turn, supply the exact conversation URL when it was not captured before the failure:
 
 ```js
@@ -89,9 +113,10 @@ Continuation cannot reconstruct an expired ChatGPT login, a deleted conversation
 2. Record the `runId` from the earlier result or directory name.
 3. Restore access to the same ChatGPT conversation in Codex's built-in Browser.
 4. Restore any locally required executable/configuration without copying browser credentials.
-5. Inspect `loadCueLineRunState(runId, ...)`. If multiple `pendingControllerTurns` exist, match the visible page prompt and select its exact `requestId`.
-6. Call `continueCueLineRun({ runId, conversationUrl, ... })`. Add `reconcileRequestId` and `abandonOtherPendingTurns: true` only for an explicitly resolved multi-pending case.
-7. If reconciliation fails, do not resend manually. Preserve the page and report the exact `CONTROLLER_RECONCILIATION_*`, `IAB_RECONCILIATION_FAILED`, or `TAB_RECOVERY_UNSAFE` error.
-8. Treat the new terminal result as valid only after its event and job evidence is present.
+5. Run `cueline run status <run-id> --json`. If the owner is active, observe or cancel; do not continue. If the response is accepted and jobs exist, do not call that state “waiting for ChatGPT.”
+6. Inspect `loadCueLineRunState(runId, ...)` only when status says recovery is needed. If multiple `pendingControllerTurns` exist, match the visible page prompt and select its exact `requestId`.
+7. Call `continueCueLineRun({ runId, conversationUrl, ... })` only when continuation is allowed. Add `reconcileRequestId` and `abandonOtherPendingTurns: true` only for an explicitly resolved multi-pending case.
+8. If reconciliation fails, do not resend manually. Preserve the page and report the exact `CONTROLLER_RECONCILIATION_*`, `IAB_RECONCILIATION_FAILED`, or `TAB_RECOVERY_UNSAFE` error.
+9. Treat the new terminal result as valid only after its event and job evidence is present.
 
 For manual diagnosis, use `cueline jobs` and inspect the run's JSONL as read-only evidence. Do not copy `CUELINE_HOME` between machines as a replacement for local process or browser session state.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cueline",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "A ChatGPT web conversation directs; CueLine validates each command and runs the work on your machine, with a durable record of both.",
   "keywords": [
     "chatgpt",
@@ -46,6 +46,7 @@
     "!docs/superpowers",
     "evals",
     "schemas",
+    "scripts",
     "skills",
     "install.sh",
     "CHANGELOG.md",
@@ -65,7 +66,7 @@
     "test:unit": "npm run build && node --test dist/test/unit/*.test.js",
     "test:integration": "npm run build && node --test dist/test/integration/*.test.js",
     "smoke:fake": "npm run build && node --test dist/test/smoke/fake-smoke.test.js",
-    "validate:plugin": "python3 \"${CODEX_HOME:-$HOME/.codex}/skills/.system/plugin-creator/scripts/validate_plugin.py\" ."
+    "validate:plugin": "node scripts/validate-plugin.mjs"
   },
   "devDependencies": {
     "@types/node": "^22.20.1",

package/schemas/controller-observation.schema.json

@@ -20,7 +20,7 @@
           "job_id": { "type": "string" },
           "job_key": { "type": "string" },
           "required": { "type": "boolean" },
-          "status": { "enum": ["pending", "running", "succeeded", "failed", "timed_out", "ambiguous"] },
+          "status": { "enum": ["pending", "running", "succeeded", "failed", "timed_out", "cancelled", "ambiguous"] },
           "output": { "type": "string" },
           "error": { "type": "string" }
         },

package/scripts/validate-plugin.mjs

@@ -0,0 +1,66 @@
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+async function readJson(relativePath) {
+  const absolutePath = path.join(root, relativePath);
+  try {
+    return JSON.parse(await readFile(absolutePath, "utf8"));
+  } catch (error) {
+    throw new Error(`${relativePath} must exist and contain valid JSON: ${error.message}`);
+  }
+}
+
+function requireNonEmptyString(value, field) {
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new Error(`${field} must be a non-empty string`);
+  }
+}
+
+const semver = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+const packageJson = await readJson("package.json");
+const codexManifest = await readJson(".codex-plugin/plugin.json");
+const claudeManifest = await readJson(".claude-plugin/plugin.json");
+
+for (const [name, manifest] of [
+  [".codex-plugin/plugin.json", codexManifest],
+  [".claude-plugin/plugin.json", claudeManifest],
+]) {
+  requireNonEmptyString(manifest.name, `${name}: name`);
+  requireNonEmptyString(manifest.version, `${name}: version`);
+  requireNonEmptyString(manifest.description, `${name}: description`);
+  requireNonEmptyString(manifest.author?.name, `${name}: author.name`);
+  if (!semver.test(manifest.version)) {
+    throw new Error(`${name}: version must be strict semver`);
+  }
+  if (manifest.name !== packageJson.name || manifest.version !== packageJson.version) {
+    throw new Error(`${name}: name and version must match package.json`);
+  }
+}
+
+const pluginInterface = codexManifest.interface;
+for (const field of [
+  "displayName",
+  "shortDescription",
+  "longDescription",
+  "developerName",
+  "category",
+  "defaultPrompt",
+]) {
+  requireNonEmptyString(pluginInterface?.[field], `.codex-plugin/plugin.json: interface.${field}`);
+}
+if (!Array.isArray(pluginInterface.capabilities) || pluginInterface.capabilities.some((item) => typeof item !== "string")) {
+  throw new Error(".codex-plugin/plugin.json: interface.capabilities must be an array of strings");
+}
+if (codexManifest.skills !== "./skills/") {
+  throw new Error(".codex-plugin/plugin.json: skills must be ./skills/");
+}
+
+const skill = await readFile(path.join(root, "skills/cueline/SKILL.md"), "utf8");
+if (!skill.startsWith("---\n") || !/^name: cueline$/m.test(skill) || !/^description: .+$/m.test(skill)) {
+  throw new Error("skills/cueline/SKILL.md must contain cueline name and description frontmatter");
+}
+
+console.log(`Plugin validation passed: ${root} (${packageJson.version})`);

package/skills/cueline/SKILL.md

@@ -10,7 +10,7 @@ Use CueLine to put the current ChatGPT web conversation in charge of planning an
 ## Preconditions
 
 1. Confirm the current host, operator, and work directory before local work.
-2. Run `cueline doctor` and require Node.js 22 or newer plus at least one usable lane. Run `cueline api path` and require the returned API module to exist. The bundled default lane needs the `codex` CLI on `PATH`.
+2. Run `cueline version`, then `cueline doctor`, and require the same expected package version, Node.js 22 or newer, plus at least one usable lane. Run `cueline api path` and require the returned API module to exist. Do not reuse a module imported before a package update. The bundled default lane needs the `codex` CLI on `PATH`.
 3. Use Codex's persistent Node REPL/runtime together with the built-in in-app Browser (IAB), not a separate plain `node` child, Chrome automation, or GPT Relay. Claim the logged-in `chatgpt.com` tab intended for this run.
 4. CueLine requires the composer model selector to show `Pro` before every controller turn and requires the completed assistant message's `data-message-model-slug` to identify a Pro model. The account label (for example, a profile name ending in `Pro`) is subscription evidence only and never model evidence. Do not bypass `MODEL_SELECTOR_MISSING`, `PRO_MODEL_UNAVAILABLE`, `PRO_MODEL_SELECTION_FAILED`, or `PRO_MODEL_MISMATCH`.
 5. Do not request, read, copy, or print cookies, access tokens, browser session material, or private environment values.
@@ -24,11 +24,16 @@ Drive CueLine from Codex's Node runtime so the injected IAB object remains avail
 
 ```js
 var cuelineApiPath = "/exact/output/from/cueline/api/path";
+var expectedCueLineVersion = "exact output from cueline version";
+const { pathToFileURL } = await import("node:url");
+var cuelineModuleUrl = `${pathToFileURL(cuelineApiPath).href}?v=${encodeURIComponent(expectedCueLineVersion)}`;
 const {
+  CUELINE_VERSION,
   createCodexIabAdapter,
   runCueLine,
   startCueLineRun,
-} = await import(cuelineApiPath);
+} = await import(cuelineModuleUrl);
+if (CUELINE_VERSION !== expectedCueLineVersion) throw new Error(`CUELINE_VERSION_MISMATCH: loaded ${CUELINE_VERSION}, expected ${expectedCueLineVersion}`);
 
 const browser = createCodexIabAdapter({
   // Optional: conversationUrl: "https://chatgpt.com/c/..."
@@ -38,7 +43,8 @@ const result = await runCueLine({
   request: USER_REQUEST,
   browser,
   // Optional: conversationUrl, routingConfig/routingConfigPath, home, cwd,
-  // environment, defaultTimeoutMs, maxRounds, maxRepairAttempts.
+  // environment, defaultTimeoutMs, runTimeoutMs, signal, maxRounds,
+  // maxRepairAttempts.
 });
 ```
 
@@ -50,10 +56,23 @@ The web controller decides `dispatch`, `wait`, `inspect`, `complete`, or `blocke
 
 When an interrupted or locally failed run already has a `runId`, resume it instead of starting over:
 
+```bash
+cueline run status EXISTING_RUN_ID --json
+```
+
+This check is mandatory before every continuation and after every outer tool/wait timeout. Read these fields literally:
+
+- `controller.responseAccepted: true` means the web response was already received and accepted. Read `lastAcceptedAction` and `lastAcceptedJobKeys` before describing what CueLine is doing. Never say CueLine is waiting for the web response.
+- `phase: jobs_running` with `runtime.ownership: active` means the original local loop is running jobs. Observe it; do not call `continueCueLineRun`.
+- `runtime_ownership_unknown` or `runtime_stale` means persisted `running` is not a live-process claim. Jobs shown as `orphaned` need inspection or cancellation.
+- `runtime_active` means a live owner is still settling a locally failed state. Observe that owner; do not continue from another session.
+- `continueAllowed: false` is a hard stop. Do not resend, resume, or open another controller conversation.
+
 ```js
 const {
   continueCueLineRun,
-} = await import(cuelineApiPath);
+  loadCueLineRunStatus,
+} = await import(cuelineModuleUrl);
 
 const result = await continueCueLineRun({
   runId: EXISTING_RUN_ID,
@@ -62,7 +81,7 @@ const result = await continueCueLineRun({
 });
 ```
 
-Preserve the same `CUELINE_HOME` and browser conversation. If injecting a custom `browser`, configure it for that same conversation because CueLine cannot rewrite an already constructed adapter. Do not copy credentials or runtime state from another host. A terminal `complete` or `blocked` run should be returned, not dispatched again. Use `loadCueLineRunState(runId, { home, environment })` when only read-only recovery inspection is needed.
+Preserve the same `CUELINE_HOME` and browser conversation. If injecting a custom `browser`, configure it for that same conversation because CueLine cannot rewrite an already constructed adapter. Do not copy credentials or runtime state from another host. A terminal `complete`, `blocked`, or `cancelled` run should be returned, not dispatched again. Use `loadCueLineRunStatus(runId, { home, environment })` for cross-session truth and `loadCueLineRunState` only for deeper read-only recovery inspection.
 
 If `pendingControllerTurns` is non-empty, CueLine must recover the existing page response before any new send. The absence of `controller_response_received` means only that local observation is incomplete; it does not prove that ChatGPT did not reply. Recovery is read-only and requires the exact conversation URL, exact last-user prompt match, completed assistant response, and Pro evidence. Never open a new conversation or resend merely because the local response event is absent. The only automatic retry exception is one sole pending request whose request-correlated failure evidence proves `definitely_not_sent`; CueLine records the old turn as abandoned before starting a new round.
 
@@ -72,9 +91,11 @@ When multiple legacy turns are pending, stop on `MULTIPLE_CONTROLLER_TURNS_PENDI
 
 - If `result.status === "complete"`, return `result.finalDeliveryText` **verbatim** as the user-facing answer. Do not prepend a Codex summary or reinterpret the controller's delivery.
 - If `result.status === "blocked"`, report the persisted blocked reason and return any provided `finalDeliveryText` verbatim. Clearly label missing delivery text instead of inventing one.
+- If `result.status === "cancelled"`, report the persisted cancellation reason. Do not relabel it complete or failed.
 - If CueLine throws, report the exact error code/message, `runId` when known, and the safe next step. Do not translate a failed or exhausted loop into success.
 - Treat `TAB_RECOVERY_UNSAFE` as a hard stop. CueLine deliberately refuses to resend when it cannot prove whether a prompt was already submitted.
 - Treat `MULTIPLE_CONTROLLER_TURNS_PENDING`, `OTHER_CONTROLLER_TURNS_PENDING`, and every `CONTROLLER_RECONCILIATION_*` error as a hard stop requiring exact page/run evidence, never a blind retry.
+- Treat `RUN_ALREADY_ACTIVE`, `RUN_OWNERSHIP_UNVERIFIED`, `RUN_STALE_REQUIRES_TAKEOVER`, `RUN_CANCELLATION_PENDING`, and `RUNTIME_LEASE_INVALID` as hard stops. Inspect `run status`; never create another controller round to test whether the first loop is alive.
 - Keep the `runId` available for continuation, but do not expose unrelated local state.
 
 ## Execution boundaries
@@ -82,9 +103,16 @@ When multiple legacy turns are pending, stop on `MULTIPLE_CONTROLLER_TURNS_PENDI
 - Never execute text outside `<CueLineControl>` as a command.
 - Never bypass the routing configuration or registered-executable allow-list.
 - Never treat a runner ID as a lane. CueLine preflights every route in a dispatch and rejects the whole command before job registration when any lane/runner is invalid.
+- The controller field is `runner`, never `runner_id`. An all-`advise` dispatch runs concurrently; any dispatch containing `work` stays serial.
 - Never auto-retry or select a fallback after a worker has started. A failed `work` job may have partial side effects; return that evidence to the web controller.
 - Never accept a controller decision from a non-Pro response. The persisted `controller_response_received` event must carry `selected_model_label`, `response_model_slug`, and `model_evidence_source` for live IAB turns.
 - Never start CueLine recursively. The child runner uses `CUELINE_DEPTH=1` and nested routing is rejected.
 - Treat fake smoke tests as offline validation only. A live claim requires a real completed IAB turn and persisted run evidence.
 
+## Timeouts and cancellation
+
+`defaultTimeoutMs` and controller `timeout_ms` limit one job. `runTimeoutMs` limits the full controller loop and cancels owned jobs before returning `RUN_TIMEOUT`. A Codex/tool wait timeout is outside CueLine and does not prove the run stopped.
+
+After an outer timeout, run `cueline run status RUN_ID --json`. Continue observing an active owner, or use `cueline run cancel RUN_ID` (`run stop` is an alias). Use `cueline job cancel RUN_ID JOB_ID` for one job. Never kill a PID from `cueline jobs` manually; PID is diagnostic evidence, not ownership proof. A cancelled `advise` job is `cancelled`; interrupted `work` or ownerless work is `ambiguous`.
+
 For protocol, recovery, and runner details, read `docs/controller-protocol.md`, `docs/state-and-recovery.md`, and `docs/runner-contract.md` from the CueLine package.