@north-light/cli 0.3.482 → 0.3.484

package/dist/daemon/crtrd.js

@@ -1,14 +1,16 @@
-var Ee=Object.defineProperty;var a=(t,n)=>Ee(t,"name",{value:n,configurable:!0});import{startPeerOutbox as Re}from"./peer/outbox.js";import{reportMachineStatus as xe}from"../core/peer/directory.js";import{createPeerRelay as Pe}from"./peer/relay-service.js";import{writeFileSync as Ie,readFileSync as De,rmSync as Te,mkdirSync as Z,existsSync as k,chmodSync as Ce}from"node:fs";import{createServer as ee}from"node:http";import{dirname as Le}from"node:path";import{envCrtrdTcp as $e}from"../shared/env.js";import{serveCanvasConversationStore as Ae}from"../core/canvas/sessions.js";import{pollRunObservers as Ne}from"./runs/observer.js";import{randomBytes as Me}from"node:crypto";import{apiSocketPath as Oe,crtrHome as Ge}from"../core/canvas/paths.js";import{activeAppUsers as Fe}from"../core/spaces/users.js";import{ensureAppSpace as He,ensureUserFiles as Be}from"../core/spaces/space.js";import{LAUNCHER_SOCKET as x}from"../launcher/spec.js";import{launcherRequest as I}from"../launcher/client.js";import{installLauncherEventSink as je}from"./launcher-events.js";import{initializeEmptyLayout as qe,layoutNeedsMigration as ze,socketDir as re}from"../core/layout.js";import{migrateLooseKeys as We}from"../core/layout-migrate/loose-keys.js";import{relocateProfileFolders as Ue}from"../core/profiles/relocate.js";import{getNode as Ke,listNodesForSupervision as te,setFrozen as ne}from"../core/canvas/index.js";import{createApiServer as Je}from"./api/server.js";import{createAppListener as Ve}from"./api/app-listener.js";import{installLocalTerminalGrant as Qe}from"../core/grants/local.js";import{onRunEventAppended as Ye}from"../core/runs/events.js";import{runNotices as Xe}from"./run-notices.js";import{createGrantSync as Ze,GRANT_SYNC_INTERVAL_S as er}from"../core/grants/sync.js";import{runRemovalCascades as rr}from"../core/grants/remove.js";import{sweepSandboxes as tr}from"../core/grants/on-sync.js";import{rebuildCronExecutions as nr}from"./cron/run-socket.js";import{hasSyncedGrants as or}from"../core/grants/mirror.js";import{readConfig as ir}from"../core/config.js";import{reconcileUndeliveredTickets as sr}from"./human/sweep.js";import{resetHandedOffDeliveries as ar}from"../core/canvas/deliveries.js";import{resetHandedOffDaemonActions as cr}from"../core/canvas/daemon-actions.js";import{sweepReviews as dr}from"./review/sweep.js";import{pidfilePath as F}from"./pidfile.js";import{rendererWarning as lr}from"../core/runtime/package-health.js";import{DEFAULT_INTERVAL_MS as pr}from"./supervise-cadence.js";import{createResumeDetector as mr}from"./resume-detector.js";import{BrokerSupervisionReconciler as fr}from"./reconcilers/broker-supervision.js";import{ControllerDeathReconciler as ur}from"./reconcilers/controller-death.js";import{NodeLifecycleReconciler as hr}from"./reconcilers/node-lifecycle/tick.js";import{NodeDeadlineReconciler as vr}from"./reconcilers/node-deadline.js";import{CronLaneReconciler as wr}from"./reconcilers/cron-lane.js";import{DeliveryLaneReconciler as gr}from"./reconcilers/delivery-lane.js";import{ActionLaneReconciler as yr}from"./reconcilers/action-lane.js";import{endLiveExecution as Sr,migrateLegacyExecutionIdentities as _r}from"../core/canvas/executions.js";import{revokePriorEpochNodeTokens as br}from"../core/canvas/node-tokens.js";import{PendingReviewSubmitReconciler as kr}from"./reconcilers/pending-review-submit.js";import{StorageMaintenanceReconciler as Er}from"./reconcilers/storage-maintenance.js";import{StorageDueWorkReconciler as Rr}from"./reconcilers/storage-due-work.js";import{BashDeadlineReconciler as xr}from"./reconcilers/bash-deadline.js";import{FaultRetryBackstopReconciler as Pr}from"./reconcilers/fault-retry-backstop.js";import{StructuredRequestReconciler as Ir}from"./reconcilers/structured-request-lane.js";import{reconcileStructuredRequestSidecars as Dr}from"./structured-requests/boot.js";import{captureLivenessSnapshot as oe,capturePidCommand as Tr,captureTeardownSnapshot as ie,isPidAlive as Cr,isAnyPidAlive as se,killProcessTreePids as ae}from"../core/canvas/pid.js";import{bindFleet as Lr,boundFleet as $r}from"../core/runtime/fleet.js";import{bindDaemonControl as Ar,clearDaemonControl as Nr}from"./control.js";import{execDaemon as Mr,spawnDaemon as Or}from"./manage.js";import{reconcileAndMigrateBoot as Gr}from"../core/canvas/boot.js";import{resolveInstallId as Fr}from"../core/canvas/install-id.js";import{setInstallId as Hr}from"../core/runtime/nodes.js";import{claimDaemonOwnership as Br,releaseDaemonOwnership as ce}from"../core/canvas/daemon-owner.js";import{migrate as jr,openDb as de,withCanvasWrite as qr,bindDaemonCanvasOpenHook as zr,clearDaemonCanvasOpenHook as le}from"../core/canvas/db.js";import{brokerSignalBus as H}from"./broker-signals/bus.js";import{brokerSignalStreams as Wr}from"./api/handlers/broker-signals.js";import{reconcilePackageDocuments as Ur}from"../core/graph/package-docs.js";import{startRepoSync as Kr}from"../core/graph/repo-sync/index.js";import{prewarmRecentRecipes as Jr,reapStaleSpares as Vr}from"../core/runtime/warm-pool.js";import{DaemonFleet as Qr}from"./fleet.js";import{BOOT_MIGRATIONS as Yr}from"./boot-migrations.js";import{applyJoinedOwner as Xr}from"./joined-owner.js";import{emitEvent as u}from"../core/events/emit.js";import{operationIdContext as S}from"../core/events/operation-id.js";import{bindDaemonEventSource as Zr}from"../core/events/source.js";import{activateCanvasImport as et,MigrationBlockedError as rt,runForcedCanvasImport as tt}from"../migrations/activation.js";import{convertLegacyProviderStore as nt,convertLegacyScopedStore as ot}from"../core/scoped-state/migrate.js";import{userScopeRoot as it}from"../core/scope.js";import{secretsDir as st}from"../core/layout.js";function B(t,n){return t.includes(` --canvas-home ${n} `)}a(B,"brokerCommandDeclaresCanvasHome");function j(t){return/ --epoch (\S+) /.exec(t)?.[1]??null}a(j,"brokerCommandEpoch");const at=5e3,pe=150;async function ct(t){const n=oe();if(n===null)throw u({level:"error",event:"daemon.census.snapshot_failed",fields:{invariant:"prior-epoch brokers are reaped before readiness"}}),new Error("prior-epoch broker census could not capture the process table");const c=Ge(),m=[];for(const[s,p]of n.processes){const y=p.command;if(p.zombie||!y.includes("broker-cli.js")||!B(y,c)||j(y)===t)continue;const _=y.trim().split(/\s+/).at(-1)??"";_===""||_.endsWith("broker-cli.js")||m.push({pid:s,nodeId:_})}let f=0;const o=[];for(const s of m){const p=Tr(s.pid);if(p===null||!p.includes("broker-cli.js")||!B(p,c)||j(p)===t||p.trim().split(/\s+/).at(-1)!==s.nodeId)continue;const y=ie(s.pid,null);if(!y.reused){try{process.platform==="linux"&&k(x)?await I({operation:"stop",pid:s.pid}):process.kill(s.pid,"SIGTERM")}catch{continue}f++,o.push({pid:s.pid,snap:y})}}const g=Date.now()+at;for(;Date.now()<g&&o.some(s=>se(s.snap.tree.length>0?s.snap.tree:[s.pid]));)await new Promise(s=>setTimeout(s,pe));let v=0;for(const s of o){const p=s.snap.tree.length>0?s.snap.tree:[s.pid];se(p)&&(process.platform==="linux"&&k(x)?await I({operation:"stop",pid:s.pid}):ae(p,"SIGKILL",s.snap.identities),v++)}v>0&&await new Promise(s=>setTimeout(s,pe));const d=oe();if(d===null)throw u({level:"error",event:"daemon.census.snapshot_failed",fields:{invariant:"prior-epoch brokers are reaped before readiness",stage:"final"}}),new Error("prior-epoch broker census could not capture the final process table");const l=[];for(const[s,p]of d.processes){const y=p.command;p.zombie||!y.includes("broker-cli.js")||B(y,c)&&j(y)!==t&&l.push(s)}if(l.length>0)throw new Error(`prior-epoch broker census could not prove termination of pid(s): ${l.join(", ")}`);u({level:"info",event:"daemon.census.completed",fields:{prior_epoch_brokers:m.length,sigtermed:f,sigkilled:v}})}a(ct,"reapPriorEpochBrokers");const dt=5e3;async function lt(t){const n=Array.from(t.entries());if(n.length===0)return;for(const[o]of n){const g=Ke(o)?.status;(g==="active"||g==="idle")&&ne(o,new Date().toISOString())}const c=n.map(([,o])=>({pid:o.pid,snap:ie(o.pid,null),exited:o.handle.exited}));for(const o of c)if(!o.snap.reused)try{process.platform==="linux"&&k(x)?await I({operation:"stop",pid:o.pid}):process.kill(o.pid,"SIGTERM")}catch{}const m=new Promise(o=>{setTimeout(o,dt).unref()});await Promise.allSettled(c.map(o=>Promise.race([o.exited.then(()=>{}),m])));const f=[];for(const o of c)Cr(o.pid)&&(process.platform==="linux"&&k(x)?await I({operation:"stop",pid:o.pid}):ae(o.snap.tree.length>0?o.snap.tree:[o.pid],"SIGKILL",o.snap.identities),f.push(o));await Promise.all(f.map(o=>o.exited));for(const[o]of n)Sr(o,{reason:"daemon-teardown"});u({level:"info",event:"daemon.fleet_teardown.completed",fields:{brokers:c.length,sigkilled:f.length}})}a(lt,"teardownFleet");function me(){Z(Le(F()),{recursive:!0}),Ie(F(),String(process.pid),"utf8")}a(me,"writePidfile");function fe(t){return typeof t=="object"&&t!==null&&t.code==="ENOENT"}a(fe,"isMissingPathError");function ue(t){const n=F();let c;try{c=De(n,"utf8")}catch(m){if(fe(m))return;throw m}if(c.trim()!==String(t))throw new Error(`daemon readiness mirror does not name this invocation (expected pid ${t})`);try{Te(n)}catch(m){if(fe(m))return;throw m}}a(ue,"removeOwnedPidfileMirror");const pt={acceptsDetachedWork:a(()=>!0,"acceptsDetachedWork"),registerDetached:a(t=>{t.catch(()=>{})},"registerDetached")},q=new fr,mt=new ur,ft=new hr,ut=new vr,ht=new wr,vt=new gr,wt=new yr,gt=new kr,yt=new Er,St=new Rr,_t=new xr,bt=new Pr,kt=new Ir;async function Et(t=Date.now(),n=pt){const c=$r(),m=await q.runFleetPreamble(c);let f,o;try{const v=te();f=v.filter(d=>d.status==="active"||d.status==="idle"),o=v.filter(d=>d.status==="done"||d.status==="canceled"||d.status==="dead")}catch(v){u({level:"error",event:"canvas.node_list.failed",error:v});return}await q.run(t,{rows:f,fleet:c,lifecycle:n}),mt.run(t,{rows:f});const g=await ft.run(t,{rows:[...f,...o],fleet:c});ut.run(t),kt.run(t),ht.run(t,{lifecycle:n}),vt.run(t,{lifecycle:n}),wt.run(t,{lifecycle:n}),gt.run(t,{lifecycle:n}),yt.run(t,{lifecycle:n,fleet:c}),St.run(t,{lifecycle:n}),Ne(),bt.run(t,{fleet:c,lifecycle:n}),await _t.run(t,{rows:f}),q.warnIfSaturated({fleet:c,lifecycle:n,thresholds:m,frozen:g})}a(Et,"superviseTick");async function Rt(t){Z(re(),{recursive:!0,mode:493}),process.platform==="linux"&&Ce(re(),493);const n=Oe();if(k(n))throw new Error(`layout refusal cannot bind occupied socket: ${n}`);const c=ee((d,l)=>{if(d.method==="GET"&&d.url==="/healthz"){l.writeHead(200,{"content-type":"application/json; charset=utf-8"}),l.end(JSON.stringify({ok:!1,daemon_up:!0,store_accessible:!1,brokers_reconciled:!1,startup_phase:"blocked",startup_blocked:"layout_migration_required"}));return}l.writeHead(503,{"content-type":"application/json; charset=utf-8"}),l.end(JSON.stringify({error:{code:"layout_migration_required",message:"run crtr sys migrate while the runtime is offline",type:"server_error",origin:"runtime",retryable:!1}}))});await new Promise((d,l)=>{c.once("error",l),c.listen(n,()=>{c.off("error",l),d()})});let m;const f=t.tcp??$e();if(f){const d=/^(.*):(\d+)$/.exec(f);if(!d||Number(d[2])>65535)throw new Error(`invalid refusal TCP address: ${f}`);const l=ee(c.listeners("request")[0]);await new Promise((s,p)=>{l.once("error",p),l.listen(Number(d[2]),d[1],()=>{l.off("error",p),s()})}),m=l}me();let o;const g=a(()=>(o??=(async()=>{c.closeAllConnections(),m?.closeAllConnections(),await Promise.all([c,m].filter(d=>d!==void 0).map(d=>new Promise((l,s)=>d.close(p=>p?s(p):l())))),ue(process.pid),process.off("SIGINT",v),process.off("SIGTERM",v)})(),o),"cleanup"),v=a(()=>{g().then(()=>process.exit(0),d=>{process.stderr.write(`[crtrd] layout refusal cleanup failed: ${String(d)}
-`),process.exit(1)})},"onSignal");return process.on("SIGINT",v),process.on("SIGTERM",v),g}a(Rt,"serveLayoutRefusal");async function xt(t={}){if(ze())return Rt(t);qe();const n=Br(Me(16).toString("hex"));if(!n.claimed){if(n.reason==="incumbent_alive")process.stderr.write(`[crtrd] already running (pid ${n.incumbentPid??"?"})
+var Ee=Object.defineProperty;var a=(t,n)=>Ee(t,"name",{value:n,configurable:!0});import{startPeerOutbox as Re}from"./peer/outbox.js";import{reportMachineStatus as xe}from"../core/peer/directory.js";import{createPeerRelay as Pe}from"./peer/relay-service.js";import{writeFileSync as Ie,readFileSync as Te,rmSync as De,mkdirSync as Z,existsSync as k,chmodSync as Ce}from"node:fs";import{createServer as ee}from"node:http";import{dirname as $e}from"node:path";import{envCrtrdTcp as Le}from"../shared/env.js";import{serveCanvasConversationStore as Ae}from"../core/canvas/sessions.js";import{pollRunObservers as Ne}from"./runs/observer.js";import{randomBytes as Me}from"node:crypto";import{apiSocketPath as Oe,crtrHome as Ge}from"../core/canvas/paths.js";import{activeAppUsers as Fe}from"../core/spaces/users.js";import{ensureAppSpace as He,ensureUserFiles as je}from"../core/spaces/space.js";import{LAUNCHER_SOCKET as x}from"../launcher/spec.js";import{launcherRequest as I}from"../launcher/client.js";import{installLauncherEventSink as Be}from"./launcher-events.js";import{initializeEmptyLayout as qe,layoutNeedsMigration as ze,socketDir as re}from"../core/layout.js";import{migrateLooseKeys as We}from"../core/layout-migrate/loose-keys.js";import{relocateProfileFolders as Ue}from"../core/profiles/relocate.js";import{getNode as Ke,listNodesForSupervision as te,setFrozen as ne}from"../core/canvas/index.js";import{createApiServer as Je}from"./api/server.js";import{createAppListener as Ve}from"./api/app-listener.js";import{installLocalTerminalGrant as Qe}from"../core/grants/local.js";import{onRunEventAppended as Ye}from"../core/runs/events.js";import{runNotices as Xe}from"./run-notices.js";import{createGrantSync as Ze,GRANT_SYNC_INTERVAL_S as er}from"../core/grants/sync.js";import{runRemovalCascades as rr}from"../core/grants/remove.js";import{sweepSandboxes as tr}from"../core/grants/on-sync.js";import{rebuildCronExecutions as nr}from"./cron/run-socket.js";import{hasSyncedGrants as or}from"../core/grants/mirror.js";import{readConfig as ir}from"../core/config.js";import{reconcileUndeliveredTickets as sr}from"./human/sweep.js";import{resetHandedOffDeliveries as ar}from"../core/canvas/deliveries.js";import{resetHandedOffDaemonActions as cr}from"../core/canvas/daemon-actions.js";import{sweepReviews as dr}from"./review/sweep.js";import{pidfilePath as F}from"./pidfile.js";import{rendererWarning as lr}from"../core/runtime/package-health.js";import{DEFAULT_INTERVAL_MS as pr}from"./supervise-cadence.js";import{createResumeDetector as mr}from"./resume-detector.js";import{BrokerSupervisionReconciler as fr}from"./reconcilers/broker-supervision.js";import{ControllerDeathReconciler as ur}from"./reconcilers/controller-death.js";import{NodeLifecycleReconciler as hr}from"./reconcilers/node-lifecycle/tick.js";import{NodeDeadlineReconciler as vr}from"./reconcilers/node-deadline.js";import{CronLaneReconciler as wr}from"./reconcilers/cron-lane.js";import{DeliveryLaneReconciler as gr}from"./reconcilers/delivery-lane.js";import{ActionLaneReconciler as yr}from"./reconcilers/action-lane.js";import{endLiveExecution as Sr,migrateLegacyExecutionIdentities as _r}from"../core/canvas/executions.js";import{revokePriorEpochNodeTokens as br}from"../core/canvas/node-tokens.js";import{PendingReviewSubmitReconciler as kr}from"./reconcilers/pending-review-submit.js";import{StorageMaintenanceReconciler as Er}from"./reconcilers/storage-maintenance.js";import{StorageDueWorkReconciler as Rr}from"./reconcilers/storage-due-work.js";import{BashDeadlineReconciler as xr}from"./reconcilers/bash-deadline.js";import{FaultRetryBackstopReconciler as Pr}from"./reconcilers/fault-retry-backstop.js";import{StructuredRequestReconciler as Ir}from"./reconcilers/structured-request-lane.js";import{reconcileStructuredRequestSidecars as Tr}from"./structured-requests/boot.js";import{captureLivenessSnapshot as oe,capturePidCommand as Dr,captureTeardownSnapshot as ie,isPidAlive as Cr,isAnyPidAlive as se,killProcessTreePids as ae}from"../core/canvas/pid.js";import{bindFleet as $r,boundFleet as Lr}from"../core/runtime/fleet.js";import{bindDaemonControl as Ar,clearDaemonControl as Nr}from"./control.js";import{execDaemon as Mr,spawnDaemon as Or}from"./manage.js";import{reconcileAndMigrateBoot as Gr}from"../core/canvas/boot.js";import{resolveInstallId as Fr}from"../core/canvas/install-id.js";import{setInstallId as Hr}from"../core/runtime/nodes.js";import{claimDaemonOwnership as jr,releaseDaemonOwnership as ce}from"../core/canvas/daemon-owner.js";import{migrate as Br,openDb as de,withCanvasWrite as qr,bindDaemonCanvasOpenHook as zr,clearDaemonCanvasOpenHook as le}from"../core/canvas/db.js";import{brokerSignalBus as H}from"./broker-signals/bus.js";import{brokerSignalStreams as Wr}from"./api/handlers/broker-signals.js";import{reconcilePackages as Ur}from"../core/graph/package-reconcile.js";import{startRepoSync as Kr}from"../core/graph/repo-sync/index.js";import{prewarmRecentRecipes as Jr,reapStaleSpares as Vr}from"../core/runtime/warm-pool.js";import{DaemonFleet as Qr}from"./fleet.js";import{BOOT_MIGRATIONS as Yr}from"./boot-migrations.js";import{applyJoinedOwner as Xr}from"./joined-owner.js";import{emitEvent as u}from"../core/events/emit.js";import{operationIdContext as S}from"../core/events/operation-id.js";import{bindDaemonEventSource as Zr}from"../core/events/source.js";import{activateCanvasImport as et,MigrationBlockedError as rt,runForcedCanvasImport as tt}from"../migrations/activation.js";import{convertLegacyProviderStore as nt,convertLegacyScopedStore as ot}from"../core/scoped-state/migrate.js";import{userScopeRoot as it}from"../core/scope.js";import{secretsDir as st}from"../core/layout.js";function j(t,n){return t.includes(` --canvas-home ${n} `)}a(j,"brokerCommandDeclaresCanvasHome");function B(t){return/ --epoch (\S+) /.exec(t)?.[1]??null}a(B,"brokerCommandEpoch");const at=5e3,pe=150;async function ct(t){const n=oe();if(n===null)throw u({level:"error",event:"daemon.census.snapshot_failed",fields:{invariant:"prior-epoch brokers are reaped before readiness"}}),new Error("prior-epoch broker census could not capture the process table");const c=Ge(),m=[];for(const[s,p]of n.processes){const y=p.command;if(p.zombie||!y.includes("broker-cli.js")||!j(y,c)||B(y)===t)continue;const _=y.trim().split(/\s+/).at(-1)??"";_===""||_.endsWith("broker-cli.js")||m.push({pid:s,nodeId:_})}let f=0;const o=[];for(const s of m){const p=Dr(s.pid);if(p===null||!p.includes("broker-cli.js")||!j(p,c)||B(p)===t||p.trim().split(/\s+/).at(-1)!==s.nodeId)continue;const y=ie(s.pid,null);if(!y.reused){try{process.platform==="linux"&&k(x)?await I({operation:"stop",pid:s.pid}):process.kill(s.pid,"SIGTERM")}catch{continue}f++,o.push({pid:s.pid,snap:y})}}const g=Date.now()+at;for(;Date.now()<g&&o.some(s=>se(s.snap.tree.length>0?s.snap.tree:[s.pid]));)await new Promise(s=>setTimeout(s,pe));let v=0;for(const s of o){const p=s.snap.tree.length>0?s.snap.tree:[s.pid];se(p)&&(process.platform==="linux"&&k(x)?await I({operation:"stop",pid:s.pid}):ae(p,"SIGKILL",s.snap.identities),v++)}v>0&&await new Promise(s=>setTimeout(s,pe));const d=oe();if(d===null)throw u({level:"error",event:"daemon.census.snapshot_failed",fields:{invariant:"prior-epoch brokers are reaped before readiness",stage:"final"}}),new Error("prior-epoch broker census could not capture the final process table");const l=[];for(const[s,p]of d.processes){const y=p.command;p.zombie||!y.includes("broker-cli.js")||j(y,c)&&B(y)!==t&&l.push(s)}if(l.length>0)throw new Error(`prior-epoch broker census could not prove termination of pid(s): ${l.join(", ")}`);u({level:"info",event:"daemon.census.completed",fields:{prior_epoch_brokers:m.length,sigtermed:f,sigkilled:v}})}a(ct,"reapPriorEpochBrokers");const dt=5e3;async function lt(t){const n=Array.from(t.entries());if(n.length===0)return;for(const[o]of n){const g=Ke(o)?.status;(g==="active"||g==="idle")&&ne(o,new Date().toISOString())}const c=n.map(([,o])=>({pid:o.pid,snap:ie(o.pid,null),exited:o.handle.exited}));for(const o of c)if(!o.snap.reused)try{process.platform==="linux"&&k(x)?await I({operation:"stop",pid:o.pid}):process.kill(o.pid,"SIGTERM")}catch{}const m=new Promise(o=>{setTimeout(o,dt).unref()});await Promise.allSettled(c.map(o=>Promise.race([o.exited.then(()=>{}),m])));const f=[];for(const o of c)Cr(o.pid)&&(process.platform==="linux"&&k(x)?await I({operation:"stop",pid:o.pid}):ae(o.snap.tree.length>0?o.snap.tree:[o.pid],"SIGKILL",o.snap.identities),f.push(o));await Promise.all(f.map(o=>o.exited));for(const[o]of n)Sr(o,{reason:"daemon-teardown"});u({level:"info",event:"daemon.fleet_teardown.completed",fields:{brokers:c.length,sigkilled:f.length}})}a(lt,"teardownFleet");function me(){Z($e(F()),{recursive:!0}),Ie(F(),String(process.pid),"utf8")}a(me,"writePidfile");function fe(t){return typeof t=="object"&&t!==null&&t.code==="ENOENT"}a(fe,"isMissingPathError");function ue(t){const n=F();let c;try{c=Te(n,"utf8")}catch(m){if(fe(m))return;throw m}if(c.trim()!==String(t))throw new Error(`daemon readiness mirror does not name this invocation (expected pid ${t})`);try{De(n)}catch(m){if(fe(m))return;throw m}}a(ue,"removeOwnedPidfileMirror");const pt={acceptsDetachedWork:a(()=>!0,"acceptsDetachedWork"),registerDetached:a(t=>{t.catch(()=>{})},"registerDetached")},q=new fr,mt=new ur,ft=new hr,ut=new vr,ht=new wr,vt=new gr,wt=new yr,gt=new kr,yt=new Er,St=new Rr,_t=new xr,bt=new Pr,kt=new Ir;async function Et(t=Date.now(),n=pt){const c=Lr(),m=await q.runFleetPreamble(c);let f,o;try{const v=te();f=v.filter(d=>d.status==="active"||d.status==="idle"),o=v.filter(d=>d.status==="done"||d.status==="canceled"||d.status==="dead")}catch(v){u({level:"error",event:"canvas.node_list.failed",error:v});return}await q.run(t,{rows:f,fleet:c,lifecycle:n}),mt.run(t,{rows:f});const g=await ft.run(t,{rows:[...f,...o],fleet:c});ut.run(t),kt.run(t),ht.run(t,{lifecycle:n}),vt.run(t,{lifecycle:n}),wt.run(t,{lifecycle:n}),gt.run(t,{lifecycle:n}),yt.run(t,{lifecycle:n,fleet:c}),St.run(t,{lifecycle:n}),Ne(),bt.run(t,{fleet:c,lifecycle:n}),await _t.run(t,{rows:f}),q.warnIfSaturated({fleet:c,lifecycle:n,thresholds:m,frozen:g})}a(Et,"superviseTick");async function Rt(t){Z(re(),{recursive:!0,mode:493}),process.platform==="linux"&&Ce(re(),493);const n=Oe();if(k(n))throw new Error(`layout refusal cannot bind occupied socket: ${n}`);const c=ee((d,l)=>{if(d.method==="GET"&&d.url==="/healthz"){l.writeHead(200,{"content-type":"application/json; charset=utf-8"}),l.end(JSON.stringify({ok:!1,daemon_up:!0,store_accessible:!1,brokers_reconciled:!1,startup_phase:"blocked",startup_blocked:"layout_migration_required"}));return}l.writeHead(503,{"content-type":"application/json; charset=utf-8"}),l.end(JSON.stringify({error:{code:"layout_migration_required",message:"run crtr sys migrate while the runtime is offline",type:"server_error",origin:"runtime",retryable:!1}}))});await new Promise((d,l)=>{c.once("error",l),c.listen(n,()=>{c.off("error",l),d()})});let m;const f=t.tcp??Le();if(f){const d=/^(.*):(\d+)$/.exec(f);if(!d||Number(d[2])>65535)throw new Error(`invalid refusal TCP address: ${f}`);const l=ee(c.listeners("request")[0]);await new Promise((s,p)=>{l.once("error",p),l.listen(Number(d[2]),d[1],()=>{l.off("error",p),s()})}),m=l}me();let o;const g=a(()=>(o??=(async()=>{c.closeAllConnections(),m?.closeAllConnections(),await Promise.all([c,m].filter(d=>d!==void 0).map(d=>new Promise((l,s)=>d.close(p=>p?s(p):l())))),ue(process.pid),process.off("SIGINT",v),process.off("SIGTERM",v)})(),o),"cleanup"),v=a(()=>{g().then(()=>process.exit(0),d=>{process.stderr.write(`[crtrd] layout refusal cleanup failed: ${String(d)}
+`),process.exit(1)})},"onSignal");return process.on("SIGINT",v),process.on("SIGTERM",v),g}a(Rt,"serveLayoutRefusal");async function xt(t={}){if(ze())return Rt(t);qe();const n=jr(Me(16).toString("hex"));if(!n.claimed){if(n.reason==="incumbent_alive")process.stderr.write(`[crtrd] already running (pid ${n.incumbentPid??"?"})
 `);else{const r=[n.incumbentPid!==void 0?`pid ${n.incumbentPid}`:void 0,n.verdict!==void 0?`verdict ${n.verdict}`:void 0].filter(i=>i!==void 0),e=r.length>0?` (${r.join(", ")})`:"";process.stderr.write(`[crtrd] claim lost: ${n.reason}${e}
 `),n.reason==="own_identity_indeterminate"&&process.stderr.write("[crtrd] cannot read its own process identity. crouter needs /proc on Linux, or the `ps` command elsewhere (Debian/Ubuntu: apt-get install procps).\n"),(n.reason==="own_identity_indeterminate"||n.reason==="incumbent_malformed")&&(process.exitCode=1)}return async()=>{}}const c=n.claim;let m=null;try{await ct(c.token),ot({kind:"user",root:it()});for(const e of Ue())process.stderr.write(`[crtrd] ${e}
 `);if(process.platform==="darwin"){const{readConfig:e,updateConfig:i}=await import("../core/config.js");if(e("user").paths?.user_files===void 0){const{homedir:w}=await import("node:os");i("user",X=>{X.paths??={},X.paths.user_files??=w()})}}await nt(st());for(const e of We())process.stderr.write(`[crtrd] ${e}
-`);jr(de()),zr(e=>H.install(e));const r=qr(e=>Ur(e));for(const e of r.conflicts)process.stderr.write(`[crtrd] plugin documents not reconciled: ${e.message}
+`);Br(de()),zr(e=>H.install(e));const r=qr(e=>Ur(e));for(const e of r.conflicts)process.stderr.write(`[crtrd] plugin documents not reconciled: ${e.message}
 `);for(const e of r.invalid)process.stderr.write(`[crtrd] package file is not a document: ${e.path}: ${e.error}
 `);for(const e of r.quarantined)process.stderr.write(`[crtrd] plugin "${e.name}" has a damaged ${e.file} (${e.reason}); ${e.movedTo!==void 0?`moved to ${e.movedTo}`:"left in place and skipped"}
-`);m=Xr(),process.platform==="linux"&&k(x)&&(je(),await I({operation:"users.sync",users:Fe()})),br(c.token)}catch(r){le(),H.close();try{const{released:e}=ce(c);if(!e)throw new Error("daemon ownership claim was not released")}catch(e){throw new AggregateError([r,e],"daemon startup failed and cleanup also failed")}throw r}let f=!0,o,g=Promise.resolve(),v=!1,d,l;const s=new Set;let p=!1,y=!1,_,$,z=!1,A,D,T,C,M;const he=mr();let E,h={phase:"initializing",message:"daemon startup is running the canvas import and normal services are unavailable",blockerPaths:[]},P="initial startup activation",ve=null;function we(){return h.phase==="ready"?null:{phase:h.phase,message:h.message,blockerPaths:h.blockerPaths}}a(we,"startupBlock");function b(r){s.add(r),r.finally(()=>{s.delete(r)}).catch(()=>{})}a(b,"registerDetached");const W={acceptsDetachedWork:a(()=>f,"acceptsDetachedWork"),registerDetached:b};Kr(W,de);async function ge(){try{f=!1,Wr.close(),le(),H.close(),d!==void 0&&(clearInterval(d),d=void 0),T!==void 0&&(clearInterval(T),T=void 0),M?.(),M=void 0;let r;do r=g,await r;while(r!==g);for(;s.size>0;)await Promise.allSettled([...s]);if(l!==void 0&&(await lt(l),l.dispose()),$!==void 0&&!z&&(z=!0,await $.close()),C!==void 0){const e=C;C=void 0,await e.stop()}if(D!==void 0){const e=D;D=void 0,await e.close()}if(A!==void 0){const e=A;A=void 0,await e.close()}if(p||(ue(process.pid),p=!0),p&&!y){const{released:e}=ce(c);if(!e)throw new Error("daemon ownership claim was not released");y=!0}}finally{Nr(),process.off("SIGINT",J),process.off("SIGTERM",V),process.off("exit",Q)}}a(ge,"cleanupAttempt");const N=1e3;let U=!1;function ye(){return U?{graceMs:N}:(U=!0,S.fresh(()=>{u({level:"info",event:"daemon.handover.armed",fields:{pid:process.pid,grace_ms:N}})}),setTimeout(()=>{Se()},N),{graceMs:N})}a(ye,"requestHandover");async function Se(){try{await R()}catch(r){const e=r instanceof Error?r.stack??r.message:String(r);process.stderr.write(`[crtrd] handover cleanup failed:
+`);for(const e of r.kinds.refused)process.stderr.write(`[crtrd] plugin "${e.plugin}" kind ${e.kind} not registered: ${e.message}
+`);for(const e of r.kinds.invalid)process.stderr.write(`[crtrd] plugin "${e.plugin}" declares invalid object kinds or scopes; no kinds registered and no app token: ${e.error}
+`);m=Xr(),process.platform==="linux"&&k(x)&&(Be(),await I({operation:"users.sync",users:Fe()})),br(c.token)}catch(r){le(),H.close();try{const{released:e}=ce(c);if(!e)throw new Error("daemon ownership claim was not released")}catch(e){throw new AggregateError([r,e],"daemon startup failed and cleanup also failed")}throw r}let f=!0,o,g=Promise.resolve(),v=!1,d,l;const s=new Set;let p=!1,y=!1,_,L,z=!1,A,T,D,C,M;const he=mr();let E,h={phase:"initializing",message:"daemon startup is running the canvas import and normal services are unavailable",blockerPaths:[]},P="initial startup activation",ve=null;function we(){return h.phase==="ready"?null:{phase:h.phase,message:h.message,blockerPaths:h.blockerPaths}}a(we,"startupBlock");function b(r){s.add(r),r.finally(()=>{s.delete(r)}).catch(()=>{})}a(b,"registerDetached");const W={acceptsDetachedWork:a(()=>f,"acceptsDetachedWork"),registerDetached:b};Kr(W,de);async function ge(){try{f=!1,Wr.close(),le(),H.close(),d!==void 0&&(clearInterval(d),d=void 0),D!==void 0&&(clearInterval(D),D=void 0),M?.(),M=void 0;let r;do r=g,await r;while(r!==g);for(;s.size>0;)await Promise.allSettled([...s]);if(l!==void 0&&(await lt(l),l.dispose()),L!==void 0&&!z&&(z=!0,await L.close()),C!==void 0){const e=C;C=void 0,await e.stop()}if(T!==void 0){const e=T;T=void 0,await e.close()}if(A!==void 0){const e=A;A=void 0,await e.close()}if(p||(ue(process.pid),p=!0),p&&!y){const{released:e}=ce(c);if(!e)throw new Error("daemon ownership claim was not released");y=!0}}finally{Nr(),process.off("SIGINT",J),process.off("SIGTERM",V),process.off("exit",Q)}}a(ge,"cleanupAttempt");const N=1e3;let U=!1;function ye(){return U?{graceMs:N}:(U=!0,S.fresh(()=>{u({level:"info",event:"daemon.handover.armed",fields:{pid:process.pid,grace_ms:N}})}),setTimeout(()=>{Se()},N),{graceMs:N})}a(ye,"requestHandover");async function Se(){try{await R()}catch(r){const e=r instanceof Error?r.stack??r.message:String(r);process.stderr.write(`[crtrd] handover cleanup failed:
 ${e}
 `),process.exit(1)}try{process.platform==="linux"&&k(x)&&(await I({operation:"daemon.handover"}),process.exit(0)),process.pid===1&&await Mr();const r=await Or({waitForJoinLock:!0});S.fresh(()=>{u({level:"info",event:"daemon.handover.completed",fields:{predecessor_pid:process.pid,successor_pid:r.pid??r.existing_pid??null,spawned:r.started}})})}catch(r){S.fresh(()=>{u({level:"error",event:"daemon.handover.successor_failed",error:r})});const e=r instanceof Error?r.message:String(r);process.stderr.write(`[crtrd] handover successor failed to start: ${e}
 `),process.exit(1)}process.exit(0)}a(Se,"performHandover");function R(){if(_!==void 0)return _;const r=ge();return _=r,r.then(()=>{_===r&&(_=void 0)},()=>{_===r&&(_=void 0)}),r}a(R,"requestCleanup");async function K(r){try{await R(),process.exit(0)}catch(e){process.exitCode=1;const i=e instanceof Error?e.stack??`${e.name}: ${e.message}`:String(e);process.stderr.write(`[crtrd] ${r} cleanup failed:
 ${i}
-`),process.exit(1)}}a(K,"handleSignal");function J(){K("SIGINT")}a(J,"onSigint");function V(){K("SIGTERM")}a(V,"onSigterm");function Q(){R().catch(()=>{})}a(Q,"onExit");function O(r){f&&(g=g.then(r).then(()=>{},e=>{S.fresh(()=>{u({level:"error",event:"daemon.lane_job.failed",error:e})})}))}a(O,"enqueue");function Y(){!f||v||(he.check()&&E&&(u({level:"info",event:"daemon.resume.detected"}),b(E().catch(()=>{}))),v=!0,O(async()=>{if(v=!1,!!f)try{await Et(Date.now(),W)}catch(r){S.fresh(()=>{u({level:"error",event:"daemon.tick.failed",error:r})})}}))}a(Y,"enqueueTick");let L=null;async function _e(){if(L!==null)throw{status:500,code:"admission_failed",message:`daemon admission previously failed: ${L instanceof Error?L.message:String(L)}`};if(h.phase==="ready")return{admitted:!1,already_admitted:!0,startup_phase:"ready"};if(h.phase!=="prepared"&&h.phase!=="recovering")throw{status:409,code:"not_prepared",message:h.message};const r=h.phase==="prepared";try{return await G(),h={phase:"ready",message:"",blockerPaths:[]},r?{admitted:!0,already_admitted:!1,startup_phase:"ready"}:{admitted:!1,already_admitted:!0,startup_phase:"ready"}}catch(e){throw L=e,{status:500,code:"admission_failed",message:`daemon admission failed: ${e instanceof Error?e.message:String(e)}`}}}a(_e,"admitStartup");async function be(r){if(P!==null)throw{status:409,code:"migration_in_progress",message:`the canvas import is already running (${P})`};P="repair";try{const e=await tt({dryRun:r.dryRun});if(r.dryRun||e.pending||h.phase!=="blocked")return{result:e,resumed:!1};if(t.prepare)return h={phase:"prepared",message:"daemon storage is prepared and normal services are unavailable until admission",blockerPaths:[]},{result:e,resumed:!1};try{return await G(),h={phase:"ready",message:"",blockerPaths:[]},{result:e,resumed:!0}}catch(i){const w=i instanceof Error?i.message:String(i);return setTimeout(()=>{R().catch(()=>{})},1e3),{result:e,resumed:!1,resumeError:w}}}finally{P=null}}a(be,"repairMigrations");async function ke(){o=t.intervalMs??pr;const r=c.token;l=new Qr({epoch:r,enqueue:O}),Lr(l),h={phase:"recovering",message:"daemon startup recovery is running and normal services are unavailable",blockerPaths:[]},S.fresh(()=>{u({level:"info",event:"daemon.started",fields:{pid:process.pid,interval_ms:o}})});const e=Fr();if(Hr(e),S.fresh(()=>{u({level:"info",event:"daemon.install_id.resolved",fields:{install_id:e}})}),S.fresh(()=>{let i;try{i=lr()}catch{return}i!==null&&u({level:"warn",event:"daemon.startup.warning",fields:{stage:"termrender",warning:i.slice(0,2048)}})}),await S.fresh(async()=>{await dr(),await sr(),ar(Date.now()),cr(Date.now())}),S.fresh(()=>{const{reconcile:i,migrated:w}=Gr(_r);i.changed&&u({level:"info",event:"daemon.boot_change.reconciled",fields:{cleared_count:i.cleared.length,same_boot_proven:i.sameBootProven}}),w.length>0&&u({level:"info",event:"daemon.pid_identity.migrated",fields:{migrated_count:w.length}})}),S.fresh(()=>{for(const i of te())i.status!=="active"||i.pi_pid!=null||i.frozen_at!=null||i.respawn_not_before!=null||(ne(i.node_id,new Date().toISOString()),u({level:"warn",event:"daemon.startup.launch_debt_recorded",node_id:i.node_id}))}),S.fresh(()=>{Dr();for(const i of Yr){const w=i.apply();w.changed&&u({level:"info",event:"daemon.boot_migration.applied",fields:{migration:i.id,...w.summary}})}}),b(nr()),E){const i=a(()=>{b(E().catch(()=>{})),b(xe().then(w=>C?.observe(w)).then(()=>{},w=>{u({level:"warn",event:"daemon.peer.status_failed",error:w})}))},"refresh");b(rr().catch(()=>{})),b(tr().then(({completion:w})=>w).catch(w=>{u({level:"error",event:"daemon.grants.sweep_failed",error:w})})),i(),T=setInterval(i,er*1e3),T.unref(),M=Re({joined:!0,register:b})}O(()=>{Vr(),Jr()}),d=setInterval(Y,o),Y()}a(ke,"completeStartup");function G(){return ve??=ke().catch(r=>{throw h={phase:"initializing",message:"daemon startup recovery failed and normal services are unavailable",blockerPaths:[]},r})}a(G,"resumeStartup");try{process.on("SIGINT",J),process.on("SIGTERM",V),process.on("exit",Q),Zr(),m!==null&&u({level:"info",event:"daemon.joined_owner.applied",fields:{owner:m.owner,rows:m.rows}}),A=await Ae();const r=c.token;Ar({epoch:r,requestHandover:ye,registerDetached:b,startupBlock:we,admitStartup:_e,repairMigrations:be}),me(),$=Je({tcp:t.tcp}),await $.ready;const e=ir("user").runtime;e?.issuer?(E=Ze(e.issuer,b),e.unsandboxed===!0&&(C=Pe({syncGrants:E})),Ye(i=>Xe().appended(i))):Qe(),e?.unsandboxed===!0&&e.listener!==void 0&&u({level:"warn",event:"daemon.app_listener.refused_unsandboxed",fields:{reason:"runtime.unsandboxed is set; runtime.listener is ignored"}}),e!==void 0&&e.listener!==void 0&&e.unsandboxed!==!0&&(D=Ve(e,()=>or(e.issuer.replace(/\/$/,"")),E),await D.ready);try{await et()}catch(i){if(P=null,i instanceof rt)return h={phase:"blocked",message:i.message,blockerPaths:i.blockerPaths},R;throw i}process.platform==="linux"&&k(x)&&(Be(),await He("app:terminal"));try{t.prepare?h={phase:"prepared",message:"daemon storage is prepared and normal services are unavailable until admission",blockerPaths:[]}:(await G(),h={phase:"ready",message:"",blockerPaths:[]})}finally{P=null}return R}catch(r){try{await R()}catch(e){throw new AggregateError([r,e],"daemon startup failed and cleanup also failed")}throw r}}a(xt,"runDaemon");var eo=xt;export{B as brokerCommandDeclaresCanvasHome,j as brokerCommandEpoch,eo as default,xt as runDaemon,Et as superviseTick,lt as teardownFleet};
+`),process.exit(1)}}a(K,"handleSignal");function J(){K("SIGINT")}a(J,"onSigint");function V(){K("SIGTERM")}a(V,"onSigterm");function Q(){R().catch(()=>{})}a(Q,"onExit");function O(r){f&&(g=g.then(r).then(()=>{},e=>{S.fresh(()=>{u({level:"error",event:"daemon.lane_job.failed",error:e})})}))}a(O,"enqueue");function Y(){!f||v||(he.check()&&E&&(u({level:"info",event:"daemon.resume.detected"}),b(E().catch(()=>{}))),v=!0,O(async()=>{if(v=!1,!!f)try{await Et(Date.now(),W)}catch(r){S.fresh(()=>{u({level:"error",event:"daemon.tick.failed",error:r})})}}))}a(Y,"enqueueTick");let $=null;async function _e(){if($!==null)throw{status:500,code:"admission_failed",message:`daemon admission previously failed: ${$ instanceof Error?$.message:String($)}`};if(h.phase==="ready")return{admitted:!1,already_admitted:!0,startup_phase:"ready"};if(h.phase!=="prepared"&&h.phase!=="recovering")throw{status:409,code:"not_prepared",message:h.message};const r=h.phase==="prepared";try{return await G(),h={phase:"ready",message:"",blockerPaths:[]},r?{admitted:!0,already_admitted:!1,startup_phase:"ready"}:{admitted:!1,already_admitted:!0,startup_phase:"ready"}}catch(e){throw $=e,{status:500,code:"admission_failed",message:`daemon admission failed: ${e instanceof Error?e.message:String(e)}`}}}a(_e,"admitStartup");async function be(r){if(P!==null)throw{status:409,code:"migration_in_progress",message:`the canvas import is already running (${P})`};P="repair";try{const e=await tt({dryRun:r.dryRun});if(r.dryRun||e.pending||h.phase!=="blocked")return{result:e,resumed:!1};if(t.prepare)return h={phase:"prepared",message:"daemon storage is prepared and normal services are unavailable until admission",blockerPaths:[]},{result:e,resumed:!1};try{return await G(),h={phase:"ready",message:"",blockerPaths:[]},{result:e,resumed:!0}}catch(i){const w=i instanceof Error?i.message:String(i);return setTimeout(()=>{R().catch(()=>{})},1e3),{result:e,resumed:!1,resumeError:w}}}finally{P=null}}a(be,"repairMigrations");async function ke(){o=t.intervalMs??pr;const r=c.token;l=new Qr({epoch:r,enqueue:O}),$r(l),h={phase:"recovering",message:"daemon startup recovery is running and normal services are unavailable",blockerPaths:[]},S.fresh(()=>{u({level:"info",event:"daemon.started",fields:{pid:process.pid,interval_ms:o}})});const e=Fr();if(Hr(e),S.fresh(()=>{u({level:"info",event:"daemon.install_id.resolved",fields:{install_id:e}})}),S.fresh(()=>{let i;try{i=lr()}catch{return}i!==null&&u({level:"warn",event:"daemon.startup.warning",fields:{stage:"termrender",warning:i.slice(0,2048)}})}),await S.fresh(async()=>{await dr(),await sr(),ar(Date.now()),cr(Date.now())}),S.fresh(()=>{const{reconcile:i,migrated:w}=Gr(_r);i.changed&&u({level:"info",event:"daemon.boot_change.reconciled",fields:{cleared_count:i.cleared.length,same_boot_proven:i.sameBootProven}}),w.length>0&&u({level:"info",event:"daemon.pid_identity.migrated",fields:{migrated_count:w.length}})}),S.fresh(()=>{for(const i of te())i.status!=="active"||i.pi_pid!=null||i.frozen_at!=null||i.respawn_not_before!=null||(ne(i.node_id,new Date().toISOString()),u({level:"warn",event:"daemon.startup.launch_debt_recorded",node_id:i.node_id}))}),S.fresh(()=>{Tr();for(const i of Yr){const w=i.apply();w.changed&&u({level:"info",event:"daemon.boot_migration.applied",fields:{migration:i.id,...w.summary}})}}),b(nr()),E){const i=a(()=>{b(E().catch(()=>{})),b(xe().then(w=>C?.observe(w)).then(()=>{},w=>{u({level:"warn",event:"daemon.peer.status_failed",error:w})}))},"refresh");b(rr().catch(()=>{})),b(tr().then(({completion:w})=>w).catch(w=>{u({level:"error",event:"daemon.grants.sweep_failed",error:w})})),i(),D=setInterval(i,er*1e3),D.unref(),M=Re({joined:!0,register:b})}O(()=>{Vr(),Jr()}),d=setInterval(Y,o),Y()}a(ke,"completeStartup");function G(){return ve??=ke().catch(r=>{throw h={phase:"initializing",message:"daemon startup recovery failed and normal services are unavailable",blockerPaths:[]},r})}a(G,"resumeStartup");try{process.on("SIGINT",J),process.on("SIGTERM",V),process.on("exit",Q),Zr(),m!==null&&u({level:"info",event:"daemon.joined_owner.applied",fields:{owner:m.owner,rows:m.rows}}),A=await Ae();const r=c.token;Ar({epoch:r,requestHandover:ye,registerDetached:b,startupBlock:we,admitStartup:_e,repairMigrations:be}),me(),L=Je({tcp:t.tcp}),await L.ready;const e=ir("user").runtime;e?.issuer?(E=Ze(e.issuer,b),e.unsandboxed===!0&&(C=Pe({syncGrants:E})),Ye(i=>Xe().appended(i))):Qe(),e?.unsandboxed===!0&&e.listener!==void 0&&u({level:"warn",event:"daemon.app_listener.refused_unsandboxed",fields:{reason:"runtime.unsandboxed is set; runtime.listener is ignored"}}),e!==void 0&&e.listener!==void 0&&e.unsandboxed!==!0&&(T=Ve(e,()=>or(e.issuer.replace(/\/$/,"")),E),await T.ready);try{await et()}catch(i){if(P=null,i instanceof rt)return h={phase:"blocked",message:i.message,blockerPaths:i.blockerPaths},R;throw i}process.platform==="linux"&&k(x)&&(je(),await He("app:terminal"));try{t.prepare?h={phase:"prepared",message:"daemon storage is prepared and normal services are unavailable until admission",blockerPaths:[]}:(await G(),h={phase:"ready",message:"",blockerPaths:[]})}finally{P=null}return R}catch(r){try{await R()}catch(e){throw new AggregateError([r,e],"daemon startup failed and cleanup also failed")}throw r}}a(xt,"runDaemon");var eo=xt;export{j as brokerCommandDeclaresCanvasHome,B as brokerCommandEpoch,eo as default,xt as runDaemon,Et as superviseTick,lt as teardownFleet};

package/dist/daemon/peer/forward.d.ts

@@ -1,9 +1,10 @@
 import { ApiError } from '../../api/errors.js';
 import type { DatabaseSync } from 'node:sqlite';
-import type { ObjectRow } from '../../core/graph/types.js';
+import type { ObjectRow, Privacy } from '../../core/graph/types.js';
 import { type Envelope, type EnvelopeCaller } from '../../core/peer/envelope.js';
 import { type PeerRequest } from '../../core/peer/client.js';
 import { type HomeDeps } from '../../core/peer/home.js';
+import { type KindDeclaration } from '../../core/peer/stubs.js';
 import { peerCall } from '../../core/peer/client.js';
 import type { RequestContext, RequestPrincipal } from '../api/router.js';
 export interface MachineLabel {
@@ -66,4 +67,6 @@ export declare function remoteStub(db: DatabaseSync, id: string, type: string, m
         handle: string;
         external_id?: string | null;
     } | null;
+    kind_decl?: KindDeclaration;
+    privacy?: Privacy;
 }): ObjectRow;

package/dist/daemon/peer/forward.js

@@ -1 +1 @@
-var x=Object.defineProperty;var r=(e,n)=>x(e,"name",{value:n,configurable:!0});import{ApiError as f}from"../../api/errors.js";import{openDb as _}from"../../core/canvas/db.js";import{getById as v,nodeObject as $}from"../../core/graph/objects.js";import{envelopeFor as g}from"../../core/peer/envelope.js";import{isUnreachable as j}from"../../core/peer/client.js";import{machineReach as D}from"../../core/peer/directory.js";import{defaultHomeDeps as O,homeOf as S,relocate as q}from"../../core/peer/home.js";import{ensureStub as k,rehomeStub as A,stubOf as E}from"../../core/peer/stubs.js";import{peerCall as F}from"../../core/peer/client.js";const C={...O,call:r((e,n,o,t)=>F(e,n,{...o===void 0?{}:{envelope:o},...t===void 0?{}:{signal:t}}),"call"),envelope:r(e=>g(e),"envelope"),label:r(async e=>{try{const n=await D(e);return{id:e,name:n?.name??e}}catch{return{id:e,name:e}}},"label")},M={current:C},N=r(e=>e.class==="person"||e.class==="broker"||e.class==="cron","originates"),m=r(e=>{const n=e?.error;return typeof n=="object"&&n!==null&&typeof n.code=="string"?n.code:null},"errorCode");function L(e,n){const o=n?.error;return new f(e,o?.code??"error",o?.message??`the home machine answered ${e}`,o?.details)}r(L,"relayError");function P(e,n){return new f(503,"runtime_unreachable",`No machine of yours answers for ${e} (unreachable: ${n.join(", ")}).`,{id:e,unreachable:n})}r(P,"unknownError");const Q=r((e,n)=>e!==null&&typeof e=="object"&&!Array.isArray(e)?{...e,machine:n}:e,"withMachine");async function T(e,n,o){const t=M.current,a=_(),u=v(a,n),l=u===null?null:E(a,u),w=e.principal;if(!N(w)){if(l!==null)throw new f(404,"not_here",`${n} is not homed on this machine (it is a stub of ${l.home_machine})`,{id:n,home_machine:l.home_machine});return{kind:"local"}}if(u!==null&&l===null)return{kind:"local"};const b={...t,call:r((s,d)=>t.call(s,d),"call")};let i=await S(a,n,{hint:e.query.get("machine"),deps:b});for(let s=0;s<2;s++){if(i.where==="nowhere"||i.where==="here"){if(l!==null)throw new f(404,"not_found",`${n} is no longer on any machine of yours`,{id:n});return{kind:"local"}}if(i.where==="unknown")return{kind:"unknown",unreachable:i.unreachable};const d=i.machine,c=await t.call(d,o,t.envelope(w)),p=await t.label(d);if(j(c))return{kind:"unknown",unreachable:[`${p.name} (${c.unreachable.reason})`]};const y=i.source!=="locate";if(c.status===404&&s===0&&(m(c.body)==="not_here"||y&&m(c.body)==="not_found")){const h=await q(a,n,d,b);if(h.where==="machine"){i=h;continue}if(h.where==="unknown")return{kind:"unknown",unreachable:h.unreachable};if(m(c.body)==="not_found")return{kind:"remote",status:c.status,body:c.body,machine:p};if(l!==null)throw new f(404,"not_found",`${n} is no longer on any machine of yours`,{id:n});return{kind:"local"}}return{kind:"remote",status:c.status,body:c.body,machine:p}}return{kind:"unknown",unreachable:[]}}r(T,"forwardVerb");function W(e){if(e.actor.kind==="person")return{sub:e.sub,act:{sub:e.via}};const{app:n,node:o,node_scopes:t,place:a}=e.actor;return{sub:e.sub,act:{sub:e.via,act:{sub:n,node:o,node_scopes:t,place:a}}}}r(W,"envelopeOfForwarded");function X(e){const n={};for(const[o,t]of e.query)o!=="machine"&&(n[o]=t);return n}r(X,"queryWithoutMachine");function Y(e,n){const o=n.principal;return o.class!=="forwarded"||o.actor.kind!=="app"||o.actor.node===null?null:k(e,o.actor.node,"node",o.via,W(o))}r(Y,"callerStub");function Z(e,n){return n.principal.class==="broker"?$(e,n.principal.node):null}r(Z,"callerNode");function ee(e,n,o,t,a){A(e,n,t);const u=a?.owner,l=u&&u.type==="app"?{id:"",type:"app",scheme:"app",external_id:u.external_id??(u.handle.startsWith("app:")?u.handle:`app:${u.handle}`),handle:u.handle}:null;return k(e,n,o,t,void 0,a===void 0?void 0:{id:n,type:o,kind:a.kind??null,name:a.name??n,...a.preview===void 0?{}:{preview:a.preview},owner:l})}r(ee,"remoteStub");export{Z as callerNode,Y as callerStub,C as defaultForwardDeps,W as envelopeOfForwarded,T as forwardVerb,M as forwarding,N as originates,X as queryWithoutMachine,L as relayError,ee as remoteStub,P as unknownError,Q as withMachine};
+var _=Object.defineProperty;var t=(e,n)=>_(e,"name",{value:n,configurable:!0});import{ApiError as p}from"../../api/errors.js";import{openDb as v}from"../../core/canvas/db.js";import{getById as x,nodeObject as $}from"../../core/graph/objects.js";import{envelopeFor as g}from"../../core/peer/envelope.js";import{isUnreachable as j}from"../../core/peer/client.js";import{machineReach as D}from"../../core/peer/directory.js";import{defaultHomeDeps as O,homeOf as S,relocate as q}from"../../core/peer/home.js";import{ensureStub as k,rehomeStub as A,stubOf as E}from"../../core/peer/stubs.js";import{peerCall as F}from"../../core/peer/client.js";const C={...O,call:t((e,n,o,a)=>F(e,n,{...o===void 0?{}:{envelope:o},...a===void 0?{}:{signal:a}}),"call"),envelope:t(e=>g(e),"envelope"),label:t(async e=>{try{const n=await D(e);return{id:e,name:n?.name??e}}catch{return{id:e,name:e}}},"label")},M={current:C},N=t(e=>e.class==="person"||e.class==="broker"||e.class==="cron","originates"),m=t(e=>{const n=e?.error;return typeof n=="object"&&n!==null&&typeof n.code=="string"?n.code:null},"errorCode");function L(e,n){const o=n?.error;return new p(e,o?.code??"error",o?.message??`the home machine answered ${e}`,o?.details)}t(L,"relayError");function P(e,n){return new p(503,"runtime_unreachable",`No machine of yours answers for ${e} (unreachable: ${n.join(", ")}).`,{id:e,unreachable:n})}t(P,"unknownError");const Q=t((e,n)=>e!==null&&typeof e=="object"&&!Array.isArray(e)?{...e,machine:n}:e,"withMachine");async function T(e,n,o){const a=M.current,r=v(),u=x(r,n),i=u===null?null:E(r,u),w=e.principal;if(!N(w)){if(i!==null)throw new p(404,"not_here",`${n} is not homed on this machine (it is a stub of ${i.home_machine})`,{id:n,home_machine:i.home_machine});return{kind:"local"}}if(u!==null&&i===null)return{kind:"local"};const b={...a,call:t((s,d)=>a.call(s,d),"call")};let l=await S(r,n,{hint:e.query.get("machine"),deps:b});for(let s=0;s<2;s++){if(l.where==="nowhere"||l.where==="here"){if(i!==null)throw new p(404,"not_found",`${n} is no longer on any machine of yours`,{id:n});return{kind:"local"}}if(l.where==="unknown")return{kind:"unknown",unreachable:l.unreachable};const d=l.machine,c=await a.call(d,o,a.envelope(w)),f=await a.label(d);if(j(c))return{kind:"unknown",unreachable:[`${f.name} (${c.unreachable.reason})`]};const y=l.source!=="locate";if(c.status===404&&s===0&&(m(c.body)==="not_here"||y&&m(c.body)==="not_found")){const h=await q(r,n,d,b);if(h.where==="machine"){l=h;continue}if(h.where==="unknown")return{kind:"unknown",unreachable:h.unreachable};if(m(c.body)==="not_found")return{kind:"remote",status:c.status,body:c.body,machine:f};if(i!==null)throw new p(404,"not_found",`${n} is no longer on any machine of yours`,{id:n});return{kind:"local"}}return{kind:"remote",status:c.status,body:c.body,machine:f}}return{kind:"unknown",unreachable:[]}}t(T,"forwardVerb");function W(e){if(e.actor.kind==="person")return{sub:e.sub,act:{sub:e.via}};const{app:n,node:o,node_scopes:a,place:r}=e.actor;return{sub:e.sub,act:{sub:e.via,act:{sub:n,node:o,node_scopes:a,place:r}}}}t(W,"envelopeOfForwarded");function X(e){const n={};for(const[o,a]of e.query)o!=="machine"&&(n[o]=a);return n}t(X,"queryWithoutMachine");function Y(e,n){const o=n.principal;return o.class!=="forwarded"||o.actor.kind!=="app"||o.actor.node===null?null:k(e,o.actor.node,"node",o.via,W(o))}t(Y,"callerStub");function Z(e,n){return n.principal.class==="broker"?$(e,n.principal.node):null}t(Z,"callerNode");function ee(e,n,o,a,r){A(e,n,a);const u=r?.owner,i=u&&u.type==="app"?{id:"",type:"app",scheme:"app",external_id:u.external_id??(u.handle.startsWith("app:")?u.handle:`app:${u.handle}`),handle:u.handle}:null;return k(e,n,o,a,void 0,r===void 0?void 0:{id:n,type:o,kind:r.kind??null,name:r.name??n,...r.preview===void 0?{}:{preview:r.preview},owner:i,...r.kind_decl===void 0?{}:{kind_decl:r.kind_decl},...r.privacy===void 0?{}:{privacy:r.privacy}})}t(ee,"remoteStub");export{Z as callerNode,Y as callerStub,C as defaultForwardDeps,W as envelopeOfForwarded,T as forwardVerb,M as forwarding,N as originates,X as queryWithoutMachine,L as relayError,ee as remoteStub,P as unknownError,Q as withMachine};

package/dist/daemon/plugin-objects/read-leaf.d.ts

@@ -0,0 +1,20 @@
+import type { DatabaseSync } from 'node:sqlite';
+import type { ObjectRow } from '../../core/graph/types.js';
+import type { RequestPrincipal } from '../api/router.js';
+export declare const READ_LEAF_DEADLINE_MS = 15000;
+export interface ReadDelegation {
+    plugin: string;
+    command: string[];
+    id: string;
+    name: string;
+}
+export type ReadLeafResult = {
+    markdown: string;
+} | {
+    unavailable: string;
+};
+/** The delegation for a custom object, or null when its kind has no read leaf or no installed plugin declares it any more (`declared=0`: an inert
+ *  kind shows the last announcement). Sync: runs inside the first read transaction. */
+export declare function readDelegationFor(db: DatabaseSync, object: ObjectRow): ReadDelegation | null;
+/** Run the declared read leaf as `principal`. Never throws. */
+export declare function runReadLeaf(d: ReadDelegation, principal: RequestPrincipal, deadlineMs?: number): Promise<ReadLeafResult>;

package/dist/daemon/plugin-objects/read-leaf.js

@@ -0,0 +1,2 @@
+var f=Object.defineProperty;var l=(n,o)=>f(n,"name",{value:o,configurable:!0});import{randomUUID as g}from"node:crypto";import{prepared as h}from"../../core/sqlite-statements.js";import{listInstalledPlugins as v}from"../../core/resolver.js";import{validatePluginCommands as b}from"../../core/command-plugins/discovery.js";import{executeExternalLeafAsync as E}from"../../core/command-plugins/transport/exec-invoke-async.js";import{invokeHttpLeaf as k}from"../../core/command-plugins/transport/http-invoke.js";import{sha256Hex as x,signedHeaderDigest as _}from"../../core/command-plugins/transport/sign.js";import{pluginAppEnv as w}from"../../core/plugin-app.js";import{callProvider as y}from"../../core/providers/call.js";import{callerFromRequest as L}from"../api/handlers/providers.js";import{signCallHeaders as P}from"../api/handlers/plugin-app-token.js";const j=15e3;function C(n,o){const a=h(n,`SELECT k.read_json, k.declared, i.scheme, i.external_id FROM object_kinds k
+    LEFT JOIN identities i ON i.object = k.owner WHERE k.name = ?`).get(o.type);if(a===void 0||a.read_json===null||a.declared===0||a.scheme!=="app"||a.external_id===null||!a.external_id.startsWith("app:"))return null;const e=JSON.parse(a.read_json).command;return{plugin:a.external_id.slice(4),command:e,id:o.id,name:o.name}}l(C,"readDelegationFor");async function J(n,o,a=j){try{const e=v("user").find(r=>r.name===n.plugin);if(e===void 0||!e.enabled)return{unavailable:`plugin ${n.plugin} is not installed`};const u={id:n.id,name:n.name};let d;if(e.manifest.provider?.id===e.name){const r=AbortSignal.timeout(a),t=y(L(o),{provider:e.name,tool:n.command.join(" "),arguments:u},{requestId:g(),signal:r});t.catch(()=>{}),d=(await Promise.race([t,new Promise((p,i)=>{r.addEventListener("abort",()=>i(new Error(`provider read leaf gave no answer within ${a} ms`)),{once:!0})})])).body}else{const r=b(e),t=r.transport;let i=r.manifest?.roots.find(m=>m.name===e.name);for(const m of n.command)i=i?.kind==="branch"?i.children.find(s=>s?.name===m):void 0;if(i?.kind!=="leaf"||t?.kind!=="exec"&&t?.kind!=="http")return{unavailable:`plugin ${n.plugin} has no read leaf ${n.command.join(" ")}`};if(t.kind==="http"){const m=i;d=await k({registration:{name:e.name,endpoint:t.endpoint,...t.authEnv!==void 0?{authEnv:t.authEnv}:{}},...r.manifest?.baseUrl!==void 0?{baseUrl:r.manifest.baseUrl}:{},timeouts:{...r.manifest?.timeouts,requestMs:a},params:m.params,rest:m.rest,output:m.output,commandPath:[e.name,...n.command]},u,void 0,{callHeaders:l(async s=>P(e.name,o,{method:s.method,url:s.url.href,body_sha256:x(s.body),..._(s.headers)}).headers,"callHeaders")})}else{if(t.executable===void 0)return{unavailable:`plugin ${n.plugin} has no read leaf ${n.command.join(" ")}`};d=await E({plugin:e,executable:t.executable,commandPath:[e.name,...n.command],output:i.output},u,{deadlineMs:a,cwd:e.root,env:{...process.env,...w(e.name)??{}}})}}const c=d?.markdown;return typeof c=="string"?{markdown:c}:{unavailable:"read leaf returned no markdown"}}catch(e){return{unavailable:e instanceof Error?e.message:String(e)}}}l(J,"runReadLeaf");export{j as READ_LEAF_DEADLINE_MS,C as readDelegationFor,J as runReadLeaf};

package/dist/types.d.ts

@@ -60,6 +60,18 @@ export type MemoryExtensionDeclaration = BooleanMemoryExtensionDeclaration | Str
 /** Field declarations owned by one plugin manifest. The plugin's `name` is
  * the namespace; keys here are its lowercase kebab-case local field names. */
 export type MemoryExtensionDeclarations = Record<string, MemoryExtensionDeclaration>;
+/** One canvas object kind a plugin declares in `object_kinds`. */
+export interface ObjectKindDeclaration {
+    description: string;
+    events: Record<string, {
+        level: number;
+        supersedes?: boolean;
+    }>;
+    /** A leaf path of the plugin's own commands, run to render an instance as markdown. */
+    read?: {
+        command: string[];
+    };
+}
 export interface PluginManifest {
     name: string;
     version?: string;
@@ -124,6 +136,10 @@ export interface PluginManifest {
     /** App-scoped env variables required by this plugin, collected during install. */
     env?: Record<string, import('./core/plugin-env.js').PluginEnvDeclaration>;
     transport?: PluginTransport;
+    /** Canvas object kinds this plugin declares, keyed by kind name (`<plugin>.<name>`). */
+    object_kinds?: Record<string, ObjectKindDeclaration>;
+    /** Canvas scopes (`crtr:objects:<verb>:<target>`) a local plugin's app credential holds. */
+    scopes?: string[];
     /** Archive source for a crouter-materialized HTTP plugin. Distinct from the invocation transport. */
     bundle?: PluginBundle;
     /** A capability provider's `bundle.json` `provider` block, copied by the

package/docs/apps/concepts/providers.md

@@ -35,11 +35,11 @@ A call is refused when the scope is missing from the grant. The refusal is an `A
 
 Some apps do not work until a provider is set up for the person. Name it under **What your app requires** on the **What it asks for** tab. The person is then taken through that provider's setup the first time they sign in. Context, for example, asks for a profile URL, and its state stays `pending` for a few minutes afterwards.
 
-Read the state on each request that depends on it. `runtime.grant.get()` returns `dependencies`, one entry per required provider, keyed by provider id (or `{}` when the app requires none):
+Read the state on each request that depends on it. `runtime.grant.get()` returns `dependencies`, one entry per setup id the app requires or lists as optional, plus any the directory implies (such as `device` for `context.deep`), keyed by setup id (or `{}` when it has none):
 
 ```ts
 const {dependencies} = await runtime.grant.get();
-const context = dependencies['context']; // {state, message?, next} or undefined
+const context = dependencies['context']; // {state, message?, next, step?} or undefined
 if (context?.state !== 'ready') {
   // Show context.message and link context.next; never hard-code either.
 }
@@ -51,8 +51,9 @@ if (context?.state !== 'ready') {
 | `pending` | The provider is working. |
 | `ready` | Calls that depend on it work. |
 | `failed` | Setup failed. `message` says why. |
+| `unavailable` | The provider does not offer this to the person's account. `message` says so; there is nothing for them to do. |
 
-`message` is the provider's own sentence, present for `pending` and `failed`. `next` is the absolute URL of the setup page for this provider and your app; add a `return_to` query parameter with your app's registered origin so the person returns to you. An entry is missing when the runtime has not synced the grant since the app began requiring the provider: treat that as `not_started`. The runtime does not block your calls for you, so refuse the dependent operation yourself. To act the moment a state turns `ready`, follow it with `oauth.watchGrants`; see [Grant changes](/docs/guides/grant-changes).
+`message` is the provider's own sentence, present for `pending`, `failed` and `unavailable`. `step` is present when the provider reports where things stand (for example `researching`); its values may grow, so ignore one you do not know. `next` is the absolute URL of the setup page for this provider and your app; `setupLink(dependency, {returnTo})` from `@north-light/sdk` adds a `return_to` with your app's registered origin so the person returns to you, and keeps the query `next` already carries. A key can contain a dot (`context.deep`). An entry is missing when the runtime has not synced the grant since the app began requiring the provider: treat that as `not_started`. The runtime does not block your calls for you, so refuse the dependent operation yourself. To act the moment a state turns `ready`, follow it with `oauth.watchGrants`; see [Grant changes](/docs/guides/grant-changes).
 
 ## Checked and not checked
 

package/docs/apps/guides/grant-changes.md

@@ -39,31 +39,33 @@ await watcher.stop();
 
 ## Wait on a provider your app requires
 
-An app whose registration `requires` a provider (the console's **What your app requires**) needs that provider set up for the person before the operations that depend on it work. The runtime does not check this for you. `grant.get()` returns `dependencies`: one entry per required provider, keyed by provider id, or `{}` when the app requires none. Read it on each request that needs the provider; do not store it.
+An app whose registration `requires` a provider (the console's **What your app requires**) needs that provider set up for the person before the operations that depend on it work. The runtime does not check this for you. `grant.get()` returns `dependencies`: one entry per setup id the app requires or lists as optional (plus any the directory implies, such as `device` for `context.deep`), keyed by setup id, or `{}` when it has none. Read it on each request that needs the provider; do not store it.
 
 ```ts
-import type {ProviderDependency} from '@north-light/sdk';
+import {setupLink, type ProviderDependency} from '@north-light/sdk';
 
-// ProviderDependency is { state: 'not_started' | 'pending' | 'ready' | 'failed'; message?: string; next: string }.
+// ProviderDependency is { state: 'not_started' | 'pending' | 'ready' | 'failed' | 'unavailable'; message?: string; next: string; step?: string }.
 const {dependencies} = await runtime.grant.get();
 const context: ProviderDependency | undefined = dependencies['context'];
 if (context?.state !== 'ready') {
   // Show the provider's own sentence and link its setup page; never hard-code either.
-  const setup = context && new URL(context.next);
-  setup?.searchParams.set('return_to', 'https://app.example.com'); // your registered redirect origin
+  // Nothing to link when the provider does not offer this to the person (`unavailable`).
+  const next = context && context.state !== 'unavailable' ? setupLink(context, {returnTo: 'https://app.example.com'}) : undefined; // your registered redirect origin
   throw new AppError('provider_setup_pending', context?.message ?? 'Finish setting up Context, then try again.', {
     status: 403,
     retryable: false,
-    details: {provider: 'context', state: context?.state ?? 'not_started', message: context?.message, next: setup?.href},
+    details: {provider: 'context', state: context?.state ?? 'not_started', message: context?.message, next},
   });
 }
 ```
 
 `AppError` stands for your app's own typed error ([Errors](/docs/errors)).
 
-- `state` is `not_started` (the person has not done their part), `pending` (the provider is working), `ready` or `failed`.
-- `message` is the provider's own sentence for `pending` and `failed`. It is absent for `not_started` and `ready`, so keep a short fallback.
-- `next` is the absolute URL of the directory's setup page for this provider and your app. Append `return_to` (your app's registered redirect origin) so the person comes back to you.
+- `state` is `not_started` (the person has not done their part), `pending` (the provider is working), `ready`, `failed`, or `unavailable` (the provider does not offer this to the person's account; there is nothing for them to do, so do not link `next`).
+- `message` is the provider's own sentence for `pending`, `failed` and `unavailable`. It is absent for `not_started` and `ready`, so keep a short fallback.
+- `step` is present when the provider reports where the person or the work is, for example `researching`. Its values belong to the provider and may grow: show a known one in your own words and ignore an unknown one. A change to `step` alone changes the grant's `version`, so `watchGrants` delivers it.
+- `next` is the absolute URL of the directory's setup page for this provider and your app. Use `setupLink(dependency, {returnTo})` to add `return_to` (your app's registered redirect origin) so the person comes back to you. It keeps the query `next` already has, such as `client_id`, and encodes `returnTo`; do not build the URL yourself.
+- A key can contain a dot. `context.deep` is a level of the `context` provider; read it as `dependencies['context.deep']`.
 - An entry is missing when the runtime has not synced the grant since the app began requiring the provider. Treat it as `not_started`.
 
 Refuse the dependent operation with `provider_setup_pending` (403), carrying `state`, `message` and `next` in `details`. To act when the state turns `ready`, use `watchGrants` above instead of polling.

package/docs/plugin/deploying.md

@@ -65,6 +65,113 @@ A definition with `version: N`, or a list of definitions with one per supported
 
 A new optional flag, a new leaf, a new optional output field and changed prose are additive.
 
+## Local plugins
+
+A plugin whose endpoint is `http://localhost`, `http://*.localhost` or another loopback host is a local plugin. crtr does not start it: run the service however you like (a terminal, launchd, a container). What crtr gives a local plugin is caller context on every call, a signature that proves the call came from crtr, and a credential for acting on the canvas.
+
+### Declaring object kinds and scopes
+
+`plugin.json` (and `bundle.json`) take two optional top-level blocks:
+
+```json
+{
+  "object_kinds": {
+    "search.page": {
+      "description": "A tracked web page",
+      "events": { "changed": { "level": 5, "supersedes": true } },
+      "read": { "command": ["page", "read"] }
+    }
+  },
+  "scopes": ["crtr:objects:link:node"]
+}
+```
+
+- A kind name's first segment is the plugin name. `events` holds at most 64 entries, each with a `level` from 1 to 10 and an optional boolean `supersedes`.
+- `read.command` is a leaf path below the plugin's root command. crtr calls it with `{ "id", "name" }` to read an instance and expects a string field `markdown`.
+- Each `scopes` entry has the form `crtr:objects:<read|watch|link|write>:<user|profile:<p>|app:<x>|node>`. A scope may not name the plugin's own space (`app:<plugin>`). A provider bundle may not declare `scopes`: a cloud app gets its scopes from directory consent.
+- Install and update refuse an invalid block and leave the installed version in place. A kind another plugin already owns is refused with `kind_owned`; the plugin's other kinds still apply.
+
+### The app token
+
+crtr gives each enabled local plugin that declares `object_kinds` or `scopes`, or uses an HTTP endpoint, one credential, `crtr_app_…`, carrying the manifest's `scopes`. The plugin uses it as `Authorization: Bearer <token>` against crtrd's `/v1` API, to register instances, link a caller, publish events and read.
+
+A service fetches the token once at startup over crtrd's unix socket, with no bearer: it asks as the person who runs it, so it must run as that user.
+
+```
+GET /v1/plugins/<name>/app-token      (over the daemon socket)
+→ { "token": "crtr_app_…", "socket": "/path/to/the/daemon.sock" }
+```
+
+The answer is `404 not_found` when the plugin is not installed, not enabled, invalid, or holds no token. Fetch it again after an update, which can change the scopes, and after a `401` (uninstall or disable revokes it).
+
+crtr never sends this token to the plugin's port: not as a bearer, a header or a body field. It reaches an exec plugin as `CRTR_APP_TOKEN` and `CRTR_DAEMON_SOCKET` in the environment. Keep it in memory or in a file with mode 0600, and never log it.
+
+### `Crtr-Caller`
+
+Every HTTP call to a plugin, local or hosted, carries who made it:
+
+```
+Crtr-Caller: node=<id>; machine=<id>; profile=<id>; run=<id>
+```
+
+The fields appear in that order. A field with no value is left out, and a call with none omits the header. A service uses `node` to link the calling node to an object it owns. The value comes from crtrd's view of the caller; a manifest cannot set `Crtr-Caller`, `Crtr-Signature` or `Crtr-Request-Id`.
+
+### `Crtr-Signature`
+
+crtrd signs a call to a local plugin when the plugin holds a token and the request goes to the origin of its installed endpoint. Any other URL gets `Crtr-Caller` and no signature.
+
+```
+Crtr-Signature: v1,t=<unix seconds>,h=<signed header names>,sig=<base64url HMAC-SHA256(token, canonical)>
+```
+
+- `h` lists, lowercase, sorted and joined with `;`, every header crtr sent except `crtr-caller` and `crtr-signature`. It always includes `crtr-request-id`, a fresh UUID per call and the signature's nonce. A retry after a connection error sends the same id and the same signature.
+- `canonical` is these lines joined with `\n`, no trailing newline:
+  1. `v1`
+  2. `t`
+  3. the HTTP method, uppercase
+  4. the request path with its query string, as received
+  5. the lowercase hex sha256 of the exact body bytes (of the empty string when there is no body)
+  6. the `Crtr-Caller` value, or an empty line
+  7. `h`
+  8. the lowercase hex sha256 of `<name>:<value>\n` for each name in `h`, in order, with each value as received: leading and trailing spaces and tabs removed, which is what Node and every other HTTP parser hands the service. crtr trims a mapped header value the same way before it signs and sends, so a padded value in a command argument is delivered without its padding
+
+A service verifies a call in this order, and answers `401` when any step fails:
+
+1. Parse the header. The version must be `v1`.
+2. `|now − t| ≤ 300` seconds.
+3. `h` must include `crtr-request-id`, be sorted, and name only headers present on the request.
+4. Recompute `canonical` from the request as received and compare the MAC with a constant-time comparison.
+5. Reject a `Crtr-Request-Id` seen in the last 600 seconds, and remember this one. Do this after step 4, so a forged request cannot fill the cache.
+6. Trust only the headers named in `h`, plus `Crtr-Caller`.
+
+```ts
+import { createHash, createHmac, timingSafeEqual } from 'node:crypto';
+
+const sha = (data: string | Buffer) => createHash('sha256').update(data).digest('hex');
+
+export function verify(token: string, req: { method: string; target: string; body: Buffer; headers: Record<string, string> },
+                       seen: Map<string, number>, now = Date.now()): boolean {
+  const [v, t, h, sig] = (req.headers['crtr-signature'] ?? '').split(',');
+  if (v !== 'v1' || !t?.startsWith('t=') || !h?.startsWith('h=') || !sig?.startsWith('sig=')) return false;
+  const seconds = Number(t.slice(2));
+  if (!Number.isInteger(seconds) || Math.abs(now / 1000 - seconds) > 300) return false;
+  const names = h.slice(2).split(';');
+  if (!names.includes('crtr-request-id') || names.some((n, i) => req.headers[n] === undefined || (i > 0 && names[i - 1]! >= n))) return false;
+  const canonical = ['v1', String(seconds), req.method.toUpperCase(), req.target, sha(req.body),
+    req.headers['crtr-caller'] ?? '', names.join(';'), sha(names.map((n) => `${n}:${req.headers[n]}\n`).join(''))].join('\n');
+  const expected = createHmac('sha256', token).update(canonical).digest();
+  const given = Buffer.from(sig.slice(4), 'base64url');
+  if (given.length !== expected.length || !timingSafeEqual(given, expected)) return false;
+  for (const [id, at] of seen) if (now - at > 600_000) seen.delete(id);
+  const id = req.headers['crtr-request-id']!;
+  if (seen.has(id)) return false;
+  seen.set(id, now);
+  return true;
+}
+```
+
+`req.headers` is keyed by lowercase name (Node's `IncomingMessage` already does this) and `req.target` is `req.url`.
+
 ## Archive response
 
 The install response is an uncompressed tar with `Content-Type: application/x-tar`. Do not configure a proxy, CDN, or framework middleware to gzip or otherwise compress it. Crtr rejects compressed archive bytes. The handler sends an ETag and supports conditional `If-None-Match` requests automatically.

package/docs/sdk/release-notes.md

@@ -7,6 +7,85 @@ description: Behavior changes in @north-light/sdk that an app must act on, newes
 
 Changes to `@north-light/sdk` that can change what an existing app sees. Newest first.
 
+## 0.3.484
+
+Plugins can now declare canvas object kinds and act on the canvas, and an app token can be granted canvas scopes. Everything below is additive: no request or response an existing app sends or reads changes, with one runtime-side exception under [Unknown bearers](#unknown-bearers-are-refused).
+
+### Plugin manifests declare `object_kinds` and `scopes` (additive)
+
+`plugin.json` and `bundle.json` take two optional top-level blocks. `object_kinds` maps a kind name (`<plugin>.<name>`, so the first segment is the plugin's own name) to `{ description, events, read? }`: `events` holds up to 64 entries `{ level: 1-10, supersedes?: boolean }`, and `read.command` is a leaf path below the plugin's root command. That leaf must answer once: a leaf declared `rest.streaming: true` is refused as a `read.command`. `scopes` lists the canvas scopes the plugin asks for. A provider bundle may not declare `scopes`: a cloud app's scopes come from directory consent. Install, update and enable refuse an invalid block and keep the installed version; a kind another owner already holds is reported as `kind_owned` and the plugin's other kinds still apply. `crtr pkg plugin install|update|enable` print these as `warnings`, plus `appScopes` (the scopes the plugin's token now carries). Plugin authors: see [Local plugins](../plugin/deploying.md#local-plugins).
+
+`ReconcilePackagesDTO` (the answer of `POST /v1/documents/reconcile-packages`) gains two optional fields: `kinds` (`applied` with `outcome` of `inserted`, `updated` or `unchanged`; `refused` with code `kind_owned`; `invalid` plugins with the reason) and `tokens` (`granted` plugins with their scopes, and `revoked` plugin names).
+
+### Canvas object scopes `crtr:objects:<verb>:<target>` (additive)
+
+`@north-light/identity` accepts `crtr:objects:<read|watch|link|write>:<user|node|profile:<id>|app:<x>>`. Each scope is its own grant: `covers` is exact equality, so `crtr:objects:write:user` does not imply `read`. The target is where the object lives:
+
+- `user`: objects in the person's space.
+- `profile:<id>`: objects below that profile.
+- `app:<x>`: nodes and custom objects of another app `x`. An app never needs a scope for its own objects, and a plugin may not declare its own `app:<plugin>` space.
+- `node`: any node, including the stub of a node on another of the account's machines.
+
+`read` lets the holder read objects of the target, `write` change them, and `link` (below) make a node watch an object the holder owns. `watch` lets a custom object that watches an object of the target read it. Holding a scope never lifts run confinement inside the owning app, and a revoked grant holds nothing. A public custom object is readable by any app that may use the owning app's tools, with no scope. The app listener now serves the canvas operations (`objects.*`, `custom-objects.*`, `docs.*`) to an app grant token under its resolved scopes; those rows answered `unknown operation` there before.
+
+### The `crtr_app_` credential and its socket fetch (additive)
+
+Each enabled local plugin that declares `object_kinds` or `scopes`, or serves over HTTP, holds one `crtr_app_…` token carrying its manifest's `scopes`. It is issued when the plugin is installed or enabled, reissued on update (the scopes can change), and revoked on uninstall or disable. crtrd accepts it as a bearer on its unix socket and TCP listener, looks it up on every request (a revoked token stops working on the next one), and treats the holder as app `app:<plugin>`.
+
+- `GET /v1/plugins/:name/app-token` (new operation `plugins.app-token`, person and broker callers) answers `{ token, socket }`, or `404 not_found` when the plugin is not installed, enabled, valid and holding a token. A service fetches it once at startup over the socket as the user who runs it. A node whose uid is not the daemon's gets `403 forbidden`.
+- An exec plugin receives the token as `CRTR_APP_TOKEN` and the socket as `CRTR_DAEMON_SOCKET` in its leaf's environment. crtr never sends the token to a plugin's HTTP port.
+- SDK: `CrtrClient.plugins.appToken(name)` and the DTO `PluginAppTokenDTO`; route helper `routes.pluginAppToken(name)`.
+
+### `Crtr-Caller` and `Crtr-Signature` on local HTTP calls (additive)
+
+Every HTTP call to a plugin carries `Crtr-Caller: node=<id>; machine=<id>; profile=<id>; run=<id>` (fields in that order, empty ones left out, header omitted when none). Calls to a local plugin's endpoint origin also carry `Crtr-Signature: v1,t=<unix seconds>,h=<signed header names>,sig=<base64url HMAC-SHA256 keyed by the plugin's token>` plus a fresh `Crtr-Request-Id`. A manifest cannot set these three header names. Provider calls carry `Crtr-Caller` too. Plugin authors: the canonical string and a reference verifier are in [Local plugins](../plugin/deploying.md#local-plugins).
+
+crtrd signs the call; the CLI never holds the token. `POST /v1/plugins/:name/call-headers` (new operation `plugins.call-headers`, person and broker callers) takes only digests, `{ method, url, body_sha256, header_names, headers_sha256 }`, and answers `{ headers }` (`Crtr-Caller`, and `Crtr-Signature` when the URL is on the installed endpoint's origin and that endpoint is loopback). Any other URL gets `Crtr-Caller` only. An unknown or disabled plugin and a provider plugin answer `404 not_found`; malformed digests answer `400 invalid_request`. SDK: `CrtrClient.plugins.callHeaders(name, request)`, `PluginCallHeadersRequestDTO`, `PluginCallHeadersDTO`, `routes.pluginCallHeaders(name)`.
+
+### Unknown bearers are refused
+
+A bearer that crtrd does not recognize is now `401` on the TCP listener as well. A runtime with no owner token used to treat a request with a bearer it did not know as the owner; now only a request with no bearer is, and a live `crtr_app_` token is that app. `crtr_pub_` and the owner token behave as before.
+
+### `custom-objects.register` takes `privacy`, and `events` is optional (additive)
+
+`RegisterCustomObjectRequestDTO.privacy?` is `public` (the default), `friends` or `private`; setting it on an existing instance changes it and publishes `configured` with `privacy` in `changed`. `events` is now optional: omit it to create or return an instance of a kind an installed plugin declares, which leaves the kind's catalog alone. Omitting it for any other kind is still `400 invalid_request`. `kind_owned` now guards only the kind catalog: registering an instance of a plugin's kind never conflicts with it.
+
+### Publishing a plugin-declared kind has new refusals
+
+`custom-objects.publish` on an instance of a kind that an installed plugin declares (or that crossed from another machine):
+
+- `404 not_here` when this machine holds only a stub of the object. Details are `{ id, home_machine }`; ask the home machine.
+- `409 kind_inert` when the kind's plugin is no longer installed and enabled.
+- `403 forbidden` unless the caller is the kind's owning app or holds the instance's publish token.
+
+Instances of kinds an app registered itself publish as before.
+
+### Watching with `link` and `watcher_machine` (additive)
+
+`POST /v1/objects/:ref/watch` and `DELETE …/watch` take an optional `watcher` ref naming a node or a custom object. A non-person app caller can name a node as the `watcher` when the object is one it owns and it holds `crtr:objects:link:<target of the watcher>`: the node then watches the object. Any miss, whatever the cause, is `404 not_found`. `watcher_machine` (body field; query parameter on DELETE) names the machine of an account's other node as the watcher; crtrd keeps a local stand-in for that node, and an event for a node that never watched the stand-in locally still reaches the node. A `watcher_machine` that is not one of the account's machines is `404`; an unreachable directory is `503 runtime_unreachable`. Custom-object watchers behave as before.
+
+A linked node receives the object's events even when it could not read the object by its own access. crtrd keeps the linking app on the watch and checks its scope and ownership again at each publish, so a revoked scope or token stops new deliveries. Across machines, both the object's home machine and the node's machine need this release.
+
+### Reading: `kind_decl`, privacy and plugin read text (additive)
+
+`ObjectDTO` gains an optional `kind_decl` (`{ name, description, events, owner }`). The runtime fills it on the object of an `objects.read` answer and of an `objects.watch` answer when the object is an instance of a custom kind, so another machine can hold a stub of it. It grants nothing. `ObjectListItemDTO` extends `ObjectDTO`, so its type carries the field, but list and search answers do not fill it. `privacy` is the field `ObjectDTO` already had: a read answered by another machine now carries the home object's `kind_decl` and `privacy` into the reader's stub, so a stub is never more readable than its home object.
+
+A read of an instance of a plugin kind whose manifest sets `read.command` runs that leaf on the home machine (15 s deadline for exec and provider plugins alike), outside the canvas transaction, and returns its `markdown` as `text`. The `read` event and the read watch are recorded once. Access is checked again after the leaf returns, and a reader who lost it gets `not_found`; an object deleted while the leaf ran answers `state: "deleted"`, and one that vanished answers `not_found`. If the leaf cannot answer (plugin not installed or disabled, timeout, no string `markdown`), `text` is the last announcement followed by `\ncontent unavailable: <reason>`. Such a read adds `data.content`: `"live"` or `"unavailable"`. A kind that is no longer declared by an installed plugin, a kind without `read.command`, and every other object read as before, with no `data.content`.
+
+### Migrations v89–v91
+
+The canvas database gains `object_kinds.read_json`, `object_kinds.source` (`register`, `manifest` or `peer`) and `object_kinds.declared` (v89), a `peer_ingested_destinations` table recording each event destination already ingested from another machine (v90), and `watches.link_app`, the app that made a watch through `link` (v91). No app action; an older runtime cannot open a database migrated by this release.
+
+## 0.3.483
+
+### `unavailable`, `step` and `setupLink` on `grant.get` dependencies (additive for the SDK; a type change for exhaustive switches)
+
+- `SetupState` gains `unavailable`: the provider does not offer this setup to the person's account. It is not `failed`. If you `switch` over `state` exhaustively, add a case; show `message` and do not link `next`.
+- `ProviderDependency` gains an optional `step: string` (for example `researching`, or `downloaded` on `device`). Its values belong to the provider and may grow: ignore one you do not know. A change to `step` alone changes `grant.get`'s `version`, so `oauth.watchGrants` delivers it.
+- `dependencies` keys may be dotted setup ids such as `context.deep`.
+- New `setupLink(dependency, {returnTo})` returns `dependency.next` with `return_to` set and URL-encoded, keeping the query `next` already has (such as `client_id`). Use it instead of building the link yourself.
+- A runtime older than this release drops a dependency whose state is `unavailable` and silently loses `step`, so an app that reads either needs a runtime on this release.
+
 ## 0.3.482
 
 ### `runs.start` accepts `deadline` (additive, no app change)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north-light/cli",
-  "version": "0.3.482",
+  "version": "0.3.484",
   "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.482",
+    "@north-light/identity": "0.3.484",
     "@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/dist/index.d.ts

@@ -22,7 +22,7 @@ export interface IdTokenClaims extends JWTPayload {
     family_name?: string;
     picture?: string;
 }
-export type Scope = 'crtr:llm' | 'crtr:act' | 'crtr:schedule' | `crtr:memory:${'read' | 'rw'}:user${'' | `:${string}`}` | 'crtr:memory:manage:user' | `crtr:memory:${'read' | 'rw'}:app:${string}` | `crtr:files:${'read' | 'rw'}:${'user' | `app:${string}`}:${string}` | 'crtr:files:share' | `crtr:${'conversations' | 'objects'}:read:app:${string}` | `crtr:objects:${'message' | 'spawn'}:app:${string}` | `crtr:peer:${string}` | `${string}:${string}`;
+export type Scope = 'crtr:llm' | 'crtr:act' | 'crtr:schedule' | `crtr:memory:${'read' | 'rw'}:user${'' | `:${string}`}` | 'crtr:memory:manage:user' | `crtr:memory:${'read' | 'rw'}:app:${string}` | `crtr:files:${'read' | 'rw'}:${'user' | `app:${string}`}:${string}` | 'crtr:files:share' | `crtr:${'conversations' | 'objects'}:read:app:${string}` | `crtr:objects:${'message' | 'spawn'}:app:${string}` | `crtr:objects:${'read' | 'watch' | 'link' | 'write'}:${'user' | 'node' | `profile:${string}` | `app:${string}`}` | `crtr:peer:${string}` | `${string}:${string}`;
 /** App-memory form keys omit the app id. */
 export declare const ENFORCED: ReadonlySet<string>;
 export declare function parseScope(value: string, grantee?: string): Scope;

package/packages/crouter-identity/dist/index.js

@@ -31,8 +31,12 @@ function selector(value) {
     match = /^crtr:files:(read|rw):(user|app:[A-Za-z0-9_-]{1,64}):(.+)$/.exec(value);
     if (match && validPath(match[3], true))
         return { kind: 'files', access: match[1], holder: match[2], path: match[3] };
-    // read, message and spawn are three unrelated scopes: `covers` is exact equality for them.
-    match = /^crtr:(?:(conversations):read|(objects):(?:read|message|spawn)):app:([A-Za-z0-9_-]{1,64})$/.exec(value);
+    // Canvas object scopes `crtr:objects:<read|watch|link|write>:<user|node|profile:<p>|app:<x>>`. They, and the
+    // message and spawn scopes below, are unrelated scopes: `covers` is exact equality for every one of them.
+    match = /^crtr:objects:(?:read|watch|link|write):(?:user|node|profile:[A-Za-z0-9_-]{1,64}|app:[A-Za-z0-9_-]{1,64})$/.exec(value);
+    if (match)
+        return { kind: 'objects', value };
+    match = /^crtr:(?:(conversations):read|(objects):(?:message|spawn)):app:([A-Za-z0-9_-]{1,64})$/.exec(value);
     if (match)
         return { kind: (match[1] ?? match[2]), value };
     match = /^crtr:peer:([A-Za-z0-9_-]{1,64})$/.exec(value);

package/packages/crouter-identity/package.json

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