@north-light/cli 0.3.436 → 0.3.438

package/dist/core/io.d.ts

@@ -57,6 +57,8 @@ interface ErrorPayloadBase {
      *  of `received` on purpose: `received` names the caller's offending VALUE, and
      *  reporting an HTTP status there is a false claim about what was sent. */
     http_status?: number;
+    /** Seconds the provider asked the caller to wait before retrying (a rate limit). */
+    retry_after_s?: number;
     next: string;
 }
 export type ErrorPayload = ErrorPayloadBase & ({
@@ -109,7 +111,12 @@ export declare function diag(message: string): void;
  *      reconstruct it verbatim so a gate/guard error (revive reopen-gate, push
  *      worktree/finalization guard, …) surfaces byte-for-byte as the leaf raised
  *      it before the re-plumb, preserving its SPECIFIC code + next.
- *   3. Otherwise map status→code (`STATUS_TO_CLI_CODE`) with the server message
+ *   3. A provider-origin refusal (`err.origin === 'provider'`) carries the
+ *      provider's own error in `details` (`{code,message,field?,next?,received?}`)
+ *      under the daemon's coarse `provider_*` code and the provider's HTTP
+ *      status. The provider's code, `next`, `field` and `Retry-After` reach the
+ *      caller unchanged; the status→code map would flatten them to `conflict`.
+ *   4. Otherwise map status→code (`STATUS_TO_CLI_CODE`) with the server message
  *      and a caller-supplied-or-default `next`. */
 export declare function apiErrorToCliError(err: ApiError, next?: string): CrtrError;
 /** Terminal error handler. Command-level failures (bad input, not-found,

package/dist/core/io.js

@@ -1,7 +1,7 @@
-var w=Object.defineProperty;var n=(e,t)=>w(e,"name",{value:t,configurable:!0});import{appendFileSync as x,statSync as E}from"node:fs";import{CrtrError as a}from"./errors.js";import{ExitCode as c}from"../types.js";import{PREVIEW_RESULT_PATH_ENV as m}from"./preview-result-path.js";import{renderError as T}from"./render.js";import{ApiError as b}from"../api/index.js";let d=!1,u;const _=256*1024;function W(e){const t=process.env[m];u=t===void 0||t===""?void 0:{path:e,jsonl:[]}}n(W,"beginPreview");function f(e){const t=process.env[m];if(t===void 0||t==="")return;const s=`${JSON.stringify({path:u?.path??"",...e})}
-`;try{if((E(t,{throwIfNoEntry:!1})?.size??0)+Buffer.byteLength(s,"utf8")>_)return;x(t,s,"utf8")}catch{}}n(f,"publishPreview");function k(e){u!==void 0&&(e!=null?f({result:e}):(u.jsonl.length>0||u.error!==void 0)&&f({...u.jsonl.length>0?{jsonl:u.jsonl}:{},...u.error===void 0?{}:{error:u.error}}))}n(k,"publishPreviewResult");function y(e){u?.jsonl.push(e)}n(y,"recordPreviewLine");function B(e){try{const t=JSON.parse(e);t!==null&&typeof t=="object"&&!Array.isArray(t)&&y(t)}catch{}}n(B,"recordPreviewJsonLine");function q(e){u!==void 0&&(u.error=e)}n(q,"recordPreviewError");function F(e){d=e}n(F,"setJsonOutput");function G(){return d}n(G,"isJsonOutput");class h extends a{static{n(this,"InputError")}payload;constructor(t,s=c.USAGE){super(t.error,t.message,s,{...t}),this.name="InputError",this.payload=t}}async function K(){if(process.stdin.isTTY)return"";const e=[];for await(const t of process.stdin)e.push(t);return Buffer.concat(e).toString("utf8")}n(K,"readStdinRaw");async function D(e=200){return process.stdin.isTTY?"":await new Promise(t=>{const s=[];let o=!1;const r=n(()=>{o||(o=!0,clearTimeout(g),process.stdin.removeListener("data",i),process.stdin.removeListener("end",p),process.stdin.removeListener("error",l),process.stdin.pause(),t(Buffer.concat(s).toString("utf8")))},"finish"),i=n(S=>s.push(S),"onData"),p=n(()=>r(),"onEnd"),l=n(()=>r(),"onError"),g=setTimeout(r,e);process.stdin.on("data",i),process.stdin.on("end",p),process.stdin.on("error",l),process.stdin.resume()})}n(D,"peekStdinRaw");function V(e){process.stdout.write(JSON.stringify(e,null,2)+`
-`)}n(V,"emit");function Y(e){y(e),process.stdout.write(JSON.stringify(e)+`
-`)}n(Y,"emitLine");function H(e){return new Promise(t=>{let s=!1;const o=n(i=>{i.code==="EPIPE"&&r(!1)},"onErr"),r=n(i=>{s||(s=!0,process.stdout.off("error",o),t(i))},"finish");process.stdout.on("error",o);try{process.stdout.write(e,i=>r(i==null))}catch{r(!1)}})}n(H,"writeStdout");function M(e){process.stderr.write(e+`
-`)}n(M,"diag");function O(e){if(e instanceof h)return e.payload;const t=e.details!==void 0?e.details:{},s=t.primaryCompleted===!0&&t.result!==null&&typeof t.result=="object"&&!Array.isArray(t.result)?N(t.result):void 0,o=t.next!==void 0?t.next:"Inspect the error and adjust the call. See -h for the schema.",r={error:e.code,message:e.message,received:t.received,field:t.field,...typeof t.http_status=="number"?{http_status:t.http_status}:{}};return s===void 0?{...r,next:o}:{...r,primaryCompleted:!0,result:s,next:o}}n(O,"payloadOf");function N(e){const t=new WeakSet;try{const s=JSON.stringify(e,(o,r)=>{if(typeof r=="bigint")return{$crtrType:"bigint",value:r.toString()};if(typeof r=="number"&&!Number.isFinite(r))return{$crtrType:"number",value:String(r)};if(typeof r>"u"||typeof r=="function"||typeof r=="symbol")return{$crtrType:typeof r};if(r!==null&&typeof r=="object"){if(t.has(r))return{$crtrType:"circular"};t.add(r)}return r});if(s!==void 0){const o=JSON.parse(s);if(o!==null&&typeof o=="object"&&!Array.isArray(o))return o}}catch{}return{$crtrType:"unavailable",message:"The completed primary result could not be represented as JSON."}}n(N,"jsonSafeResult");const R={400:"invalid_request",404:"not_found",409:"conflict",422:"unprocessable"};function A(e,t){if(e.code==="daemon_restarting")return new a("daemon_restarting",e.message,c.NETWORK,{next:"crtrd is now on the new generation \u2014 retry the command."});if(e.code==="layout_migration_required")return new a("layout_migration_required",e.message,c.NETWORK,{next:"Run `crtr sys migrate` while the runtime is offline, then restart it."});if(e.code==="daemon_unavailable")return new a("daemon_unavailable",e.message,c.NETWORK,{next:"Start it with `crtr sys daemon start`, then retry."});if(e.status===503)return new a(e.code,e.message,c.NETWORK,{next:t??"Retry the command; if it persists, inspect the unavailable service named in the error."});const s=e.details,o=Array.isArray(s?.violations)?s.violations.map(i=>`${String(i.field)} ${String(i.problem)}${i.received!==void 0?` (received ${JSON.stringify(i.received)})`:""}`):[],r=s&&typeof s.error=="string"&&typeof s.message=="string"&&typeof s.next=="string"?s:{error:R[e.status]??e.code,message:o.length>0?`${e.message}: ${o.join("; ")}`:e.message.trim()!==""?e.message:`request refused (HTTP ${e.status}, ${e.code}) with no message`,next:t??(e.status>=500?"This is a crtr bug, not a bad call. Retry; if it persists, report it (the daemon log holds the full cause).":e.status===404?"List nodes with `crtr node inspect list`.":"Inspect the error and adjust the call. See -h for the schema.")};return new h(r,P(r.error,e.status))}n(A,"apiErrorToCliError");function P(e,t){return e==="not_found"||t===404?c.NOT_FOUND:e==="ambiguous"?c.AMBIGUOUS:c.USAGE}n(P,"exitForCliCode");function j(e){if(e instanceof b){j(A(e));return}if(e instanceof a){const o=O(e);u!==void 0&&f({error:o});const r=d?JSON.stringify(o,null,2):T(o);process.stdout.write(r+`
-`),process.exitCode=e.exitCode;return}const t=e,s=t!=null&&typeof t.message=="string"?t.message:String(e);process.stderr.write(JSON.stringify({error:"internal",message:s,next:"This is a crtr bug, not a bad call. Retry; if it persists, report it."},null,2)+`
-`),process.exitCode=c.GENERAL}n(j,"handle");export{h as InputError,_ as PREVIEW_RESULT_MAX_BYTES,A as apiErrorToCliError,W as beginPreview,M as diag,V as emit,Y as emitLine,j as handle,G as isJsonOutput,D as peekStdinRaw,k as publishPreviewResult,K as readStdinRaw,q as recordPreviewError,B as recordPreviewJsonLine,y as recordPreviewLine,F as setJsonOutput,H as writeStdout};
+var x=Object.defineProperty;var s=(e,t)=>x(e,"name",{value:t,configurable:!0});import{appendFileSync as _,statSync as w}from"node:fs";import{CrtrError as a}from"./errors.js";import{ExitCode as u}from"../types.js";import{PREVIEW_RESULT_PATH_ENV as y}from"./preview-result-path.js";import{renderError as E}from"./render.js";import{ApiError as b}from"../api/index.js";let p=!1,o;const T=256*1024;function k(e){const t=process.env[y];o=t===void 0||t===""?void 0:{path:e,jsonl:[]}}s(k,"beginPreview");function l(e){const t=process.env[y];if(t===void 0||t==="")return;const n=`${JSON.stringify({path:o?.path??"",...e})}
+`;try{if((w(t,{throwIfNoEntry:!1})?.size??0)+Buffer.byteLength(n,"utf8")>T)return;_(t,n,"utf8")}catch{}}s(l,"publishPreview");function B(e){o!==void 0&&(e!=null?l({result:e}):(o.jsonl.length>0||o.error!==void 0)&&l({...o.jsonl.length>0?{jsonl:o.jsonl}:{},...o.error===void 0?{}:{error:o.error}}))}s(B,"publishPreviewResult");function m(e){o?.jsonl.push(e)}s(m,"recordPreviewLine");function q(e){try{const t=JSON.parse(e);t!==null&&typeof t=="object"&&!Array.isArray(t)&&m(t)}catch{}}s(q,"recordPreviewJsonLine");function F(e){o!==void 0&&(o.error=e)}s(F,"recordPreviewError");function G(e){p=e}s(G,"setJsonOutput");function K(){return p}s(K,"isJsonOutput");class h extends a{static{s(this,"InputError")}payload;constructor(t,n=u.USAGE){super(t.error,t.message,n,{...t}),this.name="InputError",this.payload=t}}async function z(){if(process.stdin.isTTY)return"";const e=[];for await(const t of process.stdin)e.push(t);return Buffer.concat(e).toString("utf8")}s(z,"readStdinRaw");async function D(e=200){return process.stdin.isTTY?"":await new Promise(t=>{const n=[];let r=!1;const i=s(()=>{r||(r=!0,clearTimeout(g),process.stdin.removeListener("data",f),process.stdin.removeListener("end",d),process.stdin.removeListener("error",c),process.stdin.pause(),t(Buffer.concat(n).toString("utf8")))},"finish"),f=s(S=>n.push(S),"onData"),d=s(()=>i(),"onEnd"),c=s(()=>i(),"onError"),g=setTimeout(i,e);process.stdin.on("data",f),process.stdin.on("end",d),process.stdin.on("error",c),process.stdin.resume()})}s(D,"peekStdinRaw");function V(e){process.stdout.write(JSON.stringify(e,null,2)+`
+`)}s(V,"emit");function Y(e){m(e),process.stdout.write(JSON.stringify(e)+`
+`)}s(Y,"emitLine");function H(e){return new Promise(t=>{let n=!1;const r=s(f=>{f.code==="EPIPE"&&i(!1)},"onErr"),i=s(f=>{n||(n=!0,process.stdout.off("error",r),t(f))},"finish");process.stdout.on("error",r);try{process.stdout.write(e,f=>i(f==null))}catch{i(!1)}})}s(H,"writeStdout");function M(e){process.stderr.write(e+`
+`)}s(M,"diag");function v(e){if(e instanceof h)return e.payload;const t=e.details!==void 0?e.details:{},n=t.primaryCompleted===!0&&t.result!==null&&typeof t.result=="object"&&!Array.isArray(t.result)?A(t.result):void 0,r=t.next!==void 0?t.next:"Inspect the error and adjust the call. See -h for the schema.",i={error:e.code,message:e.message,received:t.received,field:t.field,...typeof t.http_status=="number"?{http_status:t.http_status}:{},...typeof t.retry_after_s=="number"?{retry_after_s:t.retry_after_s}:{}};return n===void 0?{...i,next:r}:{...i,primaryCompleted:!0,result:n,next:r}}s(v,"payloadOf");function A(e){const t=new WeakSet;try{const n=JSON.stringify(e,(r,i)=>{if(typeof i=="bigint")return{$crtrType:"bigint",value:i.toString()};if(typeof i=="number"&&!Number.isFinite(i))return{$crtrType:"number",value:String(i)};if(typeof i>"u"||typeof i=="function"||typeof i=="symbol")return{$crtrType:typeof i};if(i!==null&&typeof i=="object"){if(t.has(i))return{$crtrType:"circular"};t.add(i)}return i});if(n!==void 0){const r=JSON.parse(n);if(r!==null&&typeof r=="object"&&!Array.isArray(r))return r}}catch{}return{$crtrType:"unavailable",message:"The completed primary result could not be represented as JSON."}}s(A,"jsonSafeResult");const O={400:"invalid_request",404:"not_found",409:"conflict",422:"unprocessable"};function N(e,t){if(e.code==="daemon_restarting")return new a("daemon_restarting",e.message,u.NETWORK,{next:"crtrd is now on the new generation \u2014 retry the command."});if(e.code==="layout_migration_required")return new a("layout_migration_required",e.message,u.NETWORK,{next:"Run `crtr sys migrate` while the runtime is offline, then restart it."});if(e.code==="daemon_unavailable")return new a("daemon_unavailable",e.message,u.NETWORK,{next:"Start it with `crtr sys daemon start`, then retry."});const n=e.details,r=R(e,n);if(e.status===503){const d=r.code??e.code,c={next:r.next??t??"Retry the command; if it persists, inspect the unavailable service named in the error."};return r.code!==void 0&&(r.field!==void 0&&(c.field=r.field),r.received!==void 0&&(c.received=r.received),r.retryAfterS!==void 0&&(c.retry_after_s=r.retryAfterS)),new a(d,e.message,u.NETWORK,c)}const i=Array.isArray(n?.violations)?n.violations.map(d=>`${String(d.field)} ${String(d.problem)}${d.received!==void 0?` (received ${JSON.stringify(d.received)})`:""}`):[],f=n&&typeof n.error=="string"&&typeof n.message=="string"&&typeof n.next=="string"?n:{error:r.code??O[e.status]??e.code,...r.field!==void 0?{field:r.field}:{},...r.received!==void 0?{received:r.received}:{},...r.retryAfterS!==void 0?{retry_after_s:r.retryAfterS}:{},message:i.length>0?`${e.message}: ${i.join("; ")}`:e.message.trim()!==""?e.message:`request refused (HTTP ${e.status}, ${e.code}) with no message`,next:r.next??t??(r.retryAfterS!==void 0?`Wait ${r.retryAfterS}s, then retry; do not retry sooner.`:e.status>=500?"This is a crtr bug, not a bad call. Retry; if it persists, report it (the daemon log holds the full cause).":e.status===404?"List nodes with `crtr node inspect list`.":"Inspect the error and adjust the call. See -h for the schema.")};return new h(f,P(f.error,e.status))}s(N,"apiErrorToCliError");function R(e,t){if(e.origin!=="provider"||t===void 0||t===null||typeof t!="object")return{};const n={};return typeof t.status=="number"&&typeof t.code=="string"&&/^[a-z][a-z0-9_]*$/.test(t.code)&&(n.code=t.code),typeof t.next=="string"&&t.next.trim()!==""&&(n.next=t.next),typeof t.field=="string"&&t.field!==""?n.field=t.field:e.param!==void 0&&(n.field=e.param),t.received!==void 0&&t.received!==null&&(n.received=t.received),typeof e.retryAfterS=="number"&&(n.retryAfterS=e.retryAfterS),n}s(R,"providerSupplied");function P(e,t){return e==="not_found"||t===404?u.NOT_FOUND:e==="ambiguous"?u.AMBIGUOUS:u.USAGE}s(P,"exitForCliCode");function $(e){if(e instanceof b){$(N(e));return}if(e instanceof a){const r=v(e);o!==void 0&&l({error:r});const i=p?JSON.stringify(r,null,2):E(r);process.stdout.write(i+`
+`),process.exitCode=e.exitCode;return}const t=e,n=t!=null&&typeof t.message=="string"?t.message:String(e);process.stderr.write(JSON.stringify({error:"internal",message:n,next:"This is a crtr bug, not a bad call. Retry; if it persists, report it."},null,2)+`
+`),process.exitCode=u.GENERAL}s($,"handle");export{h as InputError,T as PREVIEW_RESULT_MAX_BYTES,N as apiErrorToCliError,k as beginPreview,M as diag,V as emit,Y as emitLine,$ as handle,K as isJsonOutput,D as peekStdinRaw,B as publishPreviewResult,z as readStdinRaw,F as recordPreviewError,q as recordPreviewJsonLine,m as recordPreviewLine,G as setJsonOutput,H as writeStdout};

package/dist/core/render.js

@@ -1,18 +1,18 @@
-var h=Object.defineProperty;var u=(e,n)=>h(e,"name",{value:n,configurable:!0});const $=new Set(["follow_up","digest","message","next","result","content","body","guide","summary","note","reason","detail","details","hint","instruction","instructions","prompt","roadmap","report","answer","response","text"]);function m(e){return String(e).replace(/"/g,"'").replace(/\n/g," ")}u(m,"attrEsc");function l(e){return e==null?"":Array.isArray(e)?e.map(l).join(", "):typeof e=="object"?JSON.stringify(e):String(e)}u(l,"scalarStr");function y(e){const n=JSON.stringify(e,null,2);let o="```";for(;n.includes(o);)o+="`";return`${o}json
+var h=Object.defineProperty;var u=(e,n)=>h(e,"name",{value:n,configurable:!0});const $=new Set(["follow_up","digest","message","next","result","content","body","guide","summary","note","reason","detail","details","hint","instruction","instructions","prompt","roadmap","report","answer","response","text"]);function y(e){return String(e).replace(/"/g,"'").replace(/\n/g," ")}u(y,"attrEsc");function f(e){return e==null?"":Array.isArray(e)?e.map(f).join(", "):typeof e=="object"?JSON.stringify(e):String(e)}u(f,"scalarStr");function m(e){const n=JSON.stringify(e,null,2);let s="```";for(;n.includes(s);)s+="`";return`${s}json
 ${n}
-${o}`}u(y,"fencedJson");function g(e,n){return typeof n!="string"?!1:$.has(e)?!0:n.includes(`
-`)||n.length>80}u(g,"isProse");function j(e){return l(e).replace(/\|/g,"\\|").replace(/\n/g," ")}u(j,"cellEsc");function b(e,n){if(n.length===0)return`0 ${e}.`;const o=`${n.length} ${e}:`;if(n.every(s=>s!==null&&typeof s=="object"&&!Array.isArray(s))){const s=n,i=[];for(const p of s)for(const a of Object.keys(p))i.includes(a)||i.push(a);const d=`| ${i.join(" | ")} |`,t=`| ${i.map(()=>"---").join(" | ")} |`,r=s.map(p=>`| ${i.map(a=>j(p[a])).join(" | ")} |`).join(`
-`);return`${o}
+${s}`}u(m,"fencedJson");function g(e,n){return typeof n!="string"?!1:$.has(e)?!0:n.includes(`
+`)||n.length>80}u(g,"isProse");function j(e){return f(e).replace(/\|/g,"\\|").replace(/\n/g," ")}u(j,"cellEsc");function b(e,n){if(n.length===0)return`0 ${e}.`;const s=`${n.length} ${e}:`;if(n.every(o=>o!==null&&typeof o=="object"&&!Array.isArray(o))){const o=n,i=[];for(const p of o)for(const a of Object.keys(p))i.includes(a)||i.push(a);const d=`| ${i.join(" | ")} |`,t=`| ${i.map(()=>"---").join(" | ")} |`,r=o.map(p=>`| ${i.map(a=>j(p[a])).join(" | ")} |`).join(`
+`);return`${s}
 
 ${d}
 ${t}
-${r}`}const c=n.map(s=>`- ${l(s)}`).join(`
-`);return`${o}
-${c}`}u(b,"renderArray");function A(e,n){const o=n.output.map(t=>t.name);for(const t of Object.keys(e))o.includes(t)||o.push(t);const f=[],c=[],s=[];for(const t of o){const r=e[t];if(r!=null){if(Array.isArray(r)){s.push(b(t,r));continue}if(g(t,r)){c.push({name:t,text:r});continue}f.push(`- ${t}: ${l(r)}`)}}const i=[];f.length>0&&i.push(f.join(`
-`));const d=c.length>1;for(const{name:t,text:r}of c)i.push(d?`**${t}:** ${r}`:r);for(const t of s)i.push(t);return i.join(`
+${r}`}const c=n.map(o=>`- ${f(o)}`).join(`
+`);return`${s}
+${c}`}u(b,"renderArray");function _(e,n){const s=n.output.map(t=>t.name);for(const t of Object.keys(e))s.includes(t)||s.push(t);const l=[],c=[],o=[];for(const t of s){const r=e[t];if(r!=null){if(Array.isArray(r)){o.push(b(t,r));continue}if(g(t,r)){c.push({name:t,text:r});continue}l.push(`- ${t}: ${f(r)}`)}}const i=[];l.length>0&&i.push(l.join(`
+`));const d=c.length>1;for(const{name:t,text:r}of c)i.push(d?`**${t}:** ${r}`:r);for(const t of o)i.push(t);return i.join(`
 
-`)}u(A,"renderResult");function O(e){const n=[e.message];return e.received!==void 0&&e.received!==null&&e.received!==""&&n.push(`received: ${l(e.received)}`),e.field!==void 0&&n.push(`field: ${e.field}`),e.http_status!==void 0&&n.push(`http status: ${e.http_status}`),"primaryCompleted"in e&&e.primaryCompleted===!0&&(n.push("primaryCompleted: true"),n.push(`Primary result (the command already completed):
-${y(e.result)}`)),n.push(`Next: ${e.next}`),`<error code="${m(e.error)}">
+`)}u(_,"renderResult");function A(e){const n=[e.message];return e.received!==void 0&&e.received!==null&&e.received!==""&&n.push(`received: ${f(e.received)}`),e.field!==void 0&&n.push(`field: ${e.field}`),e.http_status!==void 0&&n.push(`http status: ${e.http_status}`),e.retry_after_s!==void 0&&n.push(`retry after: ${e.retry_after_s}s`),"primaryCompleted"in e&&e.primaryCompleted===!0&&(n.push("primaryCompleted: true"),n.push(`Primary result (the command already completed):
+${m(e.result)}`)),n.push(`Next: ${e.next}`),`<error code="${y(e.error)}">
 ${n.join(`
 `)}
-</error>`}u(O,"renderError");export{O as renderError,A as renderResult};
+</error>`}u(A,"renderError");export{A as renderError,_ as renderResult};

package/docs/ci-runner.md

@@ -0,0 +1,58 @@
+# CI runners and the double-run gate
+
+Crouter's suite runs on macOS (see the header of `.github/workflows/test.yml`). GitHub-hosted `macos-latest` is billed per minute and a full run is ~50 billed minutes, so the suite can run on a self-hosted Mac instead, and the push to `main` does not re-run it for a tree that already passed.
+
+## Where the macOS jobs run: `CRTR_CI_RUNNER`
+
+Repository variable `CRTR_CI_RUNNER` selects `runs-on` for the `build`, `build-output` and `lane` jobs of `test.yml`:
+
+| Value | Runs on |
+| --- | --- |
+| unset, or anything other than `self-hosted` | GitHub-hosted `macos-latest` (billed) |
+| `self-hosted` | runners labelled `[self-hosted, macOS, crouter]` (the Mac mini) |
+
+```bash
+gh variable set CRTR_CI_RUNNER --body self-hosted -R Northlight-Systems/crouter     # use the mini
+gh variable delete CRTR_CI_RUNNER -R Northlight-Systems/crouter                      # fall back to macos-latest
+```
+
+It takes effect on the next run; no commit is needed. **If the mini is offline, jobs queue until it returns (they do not fall back by themselves) — delete the variable.** Cancel and re-run anything already queued. The variable also changes the shard matrix: `self-hosted` uses 2 unit + 3 integration + 3 seam shards (8 lane jobs, 3 runner instances), hosted uses 3 + 6 + 6 (15).
+
+A pull request from a fork always runs on `macos-latest`, whatever the variable says: a self-hosted runner must never execute fork code. The repository is private and forking is disabled today, so this only guards a later change.
+
+## The Mac mini runners
+
+`scripts/ci-runner/install.sh` installs N runner instances (default 3). The mini has 10 cores and 16 GB; a lane job runs up to 8 test files at once, each with a broker and tmux, so three concurrent jobs is the ceiling before the seam lane's timeouts become the failure.
+
+Isolation, per instance `~/ci-runners/crouter-N/`:
+
+- its own runner directory and `_work` checkout;
+- its own `HOME` (`~/ci-runners/crouter-N/home`), never the account's. The suite refuses to start if `$HOME/.crouter` exists, so the account's own crouter install (`~/.crouter`, the selected runtime, `~/.local/bin/crtr`, any running `crtrd`) is neither read nor written;
+- a minimal `PATH` (Homebrew + system) that does not include the account's crtr or npm globals;
+- `hook-job-started.sh` / `hook-job-completed.sh` (`ACTIONS_RUNNER_HOOK_JOB_*`), which kill every process whose environment or command line points into that instance's directory (brokers, `crtrd`, test tmux servers, orphaned node processes) and wipe `home/.crouter*` and `_temp`. They match only that instance's path, so one instance's cleanup cannot touch another's job or the account's processes.
+
+The tests bind unix sockets under per-test temp dirs and tmux servers under the per-test `HOME`, with no fixed TCP ports, so instances do not collide.
+
+### Service
+
+Each instance is a boot-time LaunchDaemon (survives reboot and logout, runs as `silasrhyneer`): `ai.northlight.ci-runner.crouter-1` … `-3`.
+
+```bash
+sudo launchctl kickstart -k system/ai.northlight.ci-runner.crouter-1      # restart one
+sudo launchctl print system/ai.northlight.ci-runner.crouter-1 | head       # state
+tail -f ~/ci-runners/crouter-1/runner.log                                    # log
+gh api repos/Northlight-Systems/crouter/actions/runners --jq '.runners[]|[.name,.status,.busy]|@tsv'
+```
+
+Installing and upgrading: get a registration token (`gh api -X POST repos/Northlight-Systems/crouter/actions/runners/registration-token --jq .token`), run `RUNNER_TOKEN=… scripts/ci-runner/install.sh 3` on the mini, then run the `sudo launchctl bootstrap` lines it prints. Prerequisites on the mini: `tmux`, `uv`, `git` (Homebrew); Node comes from `actions/setup-node`.
+
+## No double run on `main`
+
+`publish.yml` starts with a `gate` job. It reads the pushed commit's **git tree** and looks for a workflow artifact named `tested-tree-<tree>`. `test.yml`'s final `tested` job creates that artifact only after `build`, `build-output` and every `lane` shard pass, on every pull request run and on every run of Publish's own `tests` job.
+
+- Rebase-merging a PR whose tested merge ref has the same tree as the resulting `main` commit → artifact found → `tests` is skipped and `publish` proceeds.
+- A direct push to `main`, or a merge after `main` moved (a different tree from the one the PR run tested) → no artifact → the full suite runs exactly as before. A release commit (`chore: release …`, pushed by Publish itself) changes the tree, so a PR not updated since before the latest release runs the suite once on merge; update the branch to avoid it.
+- The gate can only skip; if the lookup errors it runs the suite. `publish` runs only when `tests` passed, or was skipped *because* the gate found a record. A failed or cancelled suite never publishes.
+- Branch protection is not enabled on `main` and the gate does not depend on it: the proof is the tree, not a required check. Artifacts are kept 30 days; older trees are simply re-tested.
+
+The OIDC constraint at the top of `publish.yml` is unchanged: every publishing job is still in that file.

package/docs/sdk/guides/apps-on-northlight.md

@@ -21,7 +21,7 @@ The example app texts you, so it asks for the `sms` provider's `sms:send` scope.
 
 Open `https://account.northlight.ai/signup` and create your account. Signup texts a confirmation code to your phone, and that text is sent over iMessage, so use a phone number that has iMessage. A number that cannot receive iMessage gets "We couldn't send the text", and retrying does not help. One phone number belongs to one account.
 
-Install the CLI (`npm i -g @north-light/cli`). Joining needs `crtr` 0.3.434 or later (older versions need `crtr sys daemon stop` first and fail if a viewer is open); `crtr --version` shows yours.
+Install the CLI (`npm i -g @north-light/cli`). Joining needs `crtr` 0.3.436 or later (older versions need `crtr sys daemon stop` first and fail if a viewer is open); `crtr --version` shows yours.
 
 Then join your laptop to the account:
 
@@ -94,10 +94,10 @@ An app can only ask for scopes it has been given. It starts with `crtr:llm` and
 
 ```bash
 crtr cloud apps asks --app-id <client id> --source sms
-crtr cloud apps set-scopes --app-id <client id> --scope crtr:llm --scope crtr:act --scope sms:send
+crtr cloud apps set-scopes --app-id <client id> --add sms:send
 ```
 
-`asks` lists, per source, what the app may ask for and whether it asks now; `sms:send` is under providers, with the consent sentence "Send you text messages from Northlight's number". `set-scopes` replaces the whole list, so repeat `--scope` for every scope you want (`crtr:act` needs `crtr:llm`). Without `sms:send` the consent page does not offer it and `providers.call` for `sms` is refused. Take scope strings from `asks` and do not invent them.
+`asks` lists, per source, what the app may ask for and whether it asks now; `sms:send` is under providers, with the consent sentence "Send you text messages from Northlight's number". `set-scopes --add` adds to the list the app has now and leaves the rest alone; `--remove` drops a scope that is in it (`crtr:act` needs `crtr:llm`, so drop both together). `crtr cloud apps asks --app-id <client id> --requested` shows exactly what the app asks for now. To replace the whole list instead, repeat `--scope` for every scope you want, or pass `--clear`. The console's **What it asks for** tab does the same with an **Add permissions** search. Without `sms:send` the consent page does not offer it and `providers.call` for `sms` is refused. Take scope strings from `asks` and do not invent them.
 
 If your app does not work without a provider being set up first (Doppel needs Context), name it:
 
@@ -247,9 +247,9 @@ Your Northlight chat agent at `https://chat.northlight.ai` can run the same comm
 | `crtr cloud apps get --app-id <id>` | Shows the registration. |
 | `crtr cloud apps update --app-id <id> --name … / --origin … / --logo … / --justification …` | Changes the profile fields you pass. |
 | `crtr cloud apps set-redirect-uris --app-id <id> --redirect-uri …` | Replaces the whole redirect URI list; repeat the flag for each. |
-| `crtr cloud apps asks --app-id <id>` | Lists what an app may ask for, with whether it asks now. Large sources such as `integrations` print as a count. Narrow it with `--query sms:send`, `--source sms`, `--group providers\|apps\|agents\|space`, or `--query <text>`; for example `crtr cloud apps asks --app-id <id> --source sms`. |
-| `crtr cloud apps set-scopes --app-id <id> --scope …` | Replaces the scope list. Repeat `--scope` for every scope; `--clear` empties it; `crtr:act` needs `crtr:llm`. |
-| `crtr cloud apps set-requires --app-id <id> --provider …` | Names providers your app does not work without (for example `context`); `--clear` empties it. |
+| `crtr cloud apps asks --app-id <id>` | Lists what an app may ask for, with whether it asks now. Large sources such as `integrations` print as a count. Narrow it with `--query sms:send`, `--source sms`, `--group providers\|apps\|agents\|space`, or `--query <text>`; `--requested` lists only what the app asks for now. For example `crtr cloud apps asks --app-id <id> --source sms`. |
+| `crtr cloud apps set-scopes --app-id <id> --add … --remove …` | Edits the scope list the app has now; repeat `--add`/`--remove` per scope. Removing a scope that is not in the list is refused. Or replace the whole list with repeated `--scope`; `--clear` empties it. `crtr:act` needs `crtr:llm`. |
+| `crtr cloud apps set-requires --app-id <id> --add … --remove …` | Edits the providers your app does not work without (for example `context`). Or replace the list with repeated `--provider`; `--clear` empties it. |
 | `crtr cloud apps keys add --app-id <id> --jwk '<public JWK>'` | Adds a signing key beside any existing one. Answers `created: false` if that key is already on the app. `keygen --app` calls it for you. |
 | `crtr cloud apps keys list --app-id <id>` | Lists the keys with their `kid` and `active` or `retired` status. |
 | `crtr cloud apps keys retire --app-id <id> --kid <kid>` | Retires a key so it no longer signs in. |
@@ -282,6 +282,22 @@ crtr cloud apps set-listing --app-id <client id> --listed true --price free \
 
 `--text-welcome` is one or two plain sentences, at most 120 characters, with no links. Agents can install an app for people by text only while it is listed (`--listed true`). `crtr cloud apps install --app-id <client id>` sends the signed-in person a text with the install link. Run it only for yourself or for a person who asked: it sends a real text.
 
+### Developing alongside your live app
+
+Once your app is live, you can keep developing on your laptop against production while the live app keeps running. There are two ways to do it.
+
+**Add your localhost callback to the live app.** This is the simplest, and it is fine for most apps. An app can hold several redirect URIs, and each sign-in returns to the one its request names, so your deployed server and your laptop can both sign people in at once:
+
+```bash
+crtr cloud apps set-redirect-uris --app-id <client id> \
+  --redirect-uri https://app.example.com/auth/callback \
+  --redirect-uri http://localhost:3000/auth/callback
+```
+
+`set-redirect-uris` replaces the whole list, so name the live URI too. Give your laptop its own signing key beside the deployed one (`keygen --app` adds it; an app holds at most 2 active keys), so you never copy the production private key to your laptop. Both servers share everything else: the same people, their grants, the app's space and the scopes the app asks for. A scope you add while developing changes what the live app asks of everyone. The origin, `login_start_url` and run notice URL each hold one value, so they keep pointing at the deployed app.
+
+**Register a separate development app.** Do this when you are changing what the app asks for, or need data and grants of its own that live people never touch. Run `crtr cloud apps register` again with a name such as "Texty (dev)", a `localhost` origin and redirect URI, and its own key. It starts in testing and stays there, so only you and the testers you add can sign in, and it never appears in the marketplace. Point your laptop's environment file at its client id. This is how Google recommends separating tiers too: a separate project for development and for production.
+
 ### Rotate keys
 
 Add a new key beside the old one, switch, verify with a real sign-in, then retire the old key:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north-light/cli",
-  "version": "0.3.436",
+  "version": "0.3.438",
   "description": "crtr — agent runtime with memory, plugins, and marketplaces",
   "type": "module",
   "main": "dist/index.js",
@@ -137,7 +137,7 @@
   },
   "license": "UNLICENSED",
   "dependencies": {
-    "@north-light/identity": "0.3.436",
+    "@north-light/identity": "0.3.438",
     "@earendil-works/pi-agent-core": "1.1.0",
     "@earendil-works/pi-ai": "1.1.0",
     "@earendil-works/pi-coding-agent": "1.1.0",

package/packages/crouter-identity/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north-light/identity",
-  "version": "0.3.436",
+  "version": "0.3.438",
   "description": "Northlight access-token verification and scope rules",
   "type": "module",
   "main": "./dist/index.js",

package/runtime.lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@north-light/cli",
-  "version": "0.3.436",
+  "version": "0.3.438",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@north-light/cli",
-      "version": "0.3.436",
+      "version": "0.3.438",
       "hasInstallScript": true,
       "license": "UNLICENSED",
       "workspaces": [
@@ -18,7 +18,7 @@
         "@earendil-works/pi-ai": "1.1.0",
         "@earendil-works/pi-coding-agent": "1.1.0",
         "@earendil-works/pi-tui": "1.1.0",
-        "@north-light/identity": "0.3.436",
+        "@north-light/identity": "0.3.438",
         "cron-parser": "^5.6.0",
         "esbuild": "^0.27.7",
         "jose": "^6.2.12",
@@ -12095,17 +12095,17 @@
     },
     "packages/crouter-api": {
       "name": "@north-light/api",
-      "version": "0.3.436",
+      "version": "0.3.438",
       "license": "UNLICENSED"
     },
     "packages/crouter-env-docker": {
       "name": "@north-light/env-docker",
-      "version": "0.3.436",
+      "version": "0.3.438",
       "license": "UNLICENSED"
     },
     "packages/crouter-identity": {
       "name": "@north-light/identity",
-      "version": "0.3.436",
+      "version": "0.3.438",
       "license": "UNLICENSED",
       "dependencies": {
         "jose": "^6.2.1"
@@ -12113,20 +12113,20 @@
     },
     "packages/crouter-plugin": {
       "name": "@north-light/plugin",
-      "version": "0.3.436",
+      "version": "0.3.438",
       "license": "UNLICENSED",
       "dependencies": {
-        "@north-light/api": "0.3.436",
-        "@north-light/identity": "0.3.436"
+        "@north-light/api": "0.3.438",
+        "@north-light/identity": "0.3.438"
       }
     },
     "packages/crouter-sdk": {
       "name": "@north-light/sdk",
-      "version": "0.3.436",
+      "version": "0.3.438",
       "license": "UNLICENSED",
       "dependencies": {
-        "@north-light/api": "0.3.436",
-        "@north-light/identity": "0.3.436",
+        "@north-light/api": "0.3.438",
+        "@north-light/identity": "0.3.438",
         "jose": "^6.2.1"
       },
       "bin": {