elanous 0.2.10 → 0.2.12

package/src/llm/mission-router.ts

@@ -5,10 +5,9 @@
 // mission. Tier 1 is a pure heuristic — Korean + English regex over
 // the input plus attachment + length signals. No I/O, no network.
 //
-// Tier 2 (local LLM grammar-constrained classifier · P1-3) and Tier 3
-// (cloud LLM · deferred) plug into this same `MissionRouter` interface
-// via composition — the predict() implementation is replaced at
-// factory time, the public surface stays stable so consumers
+// Tier 2 (injected LLM classifier · P1-3) uses the classify-role judge layer.
+// Tier 3 (cloud LLM · deferred) can plug into this same `MissionRouter` interface;
+// the public surface stays stable so consumers
 // (`elanous/route/predict` envelope · iOS chip · …) don't churn.
 //
 // Default mission → provider map mirrors the ROADMAP §3.1 table:
@@ -23,6 +22,8 @@
 // flow through MissionRoutingConfig — pass the user-config slice into
 // createMissionRouter({ config }) at boot.
 
+import { judge } from './judge-layer.js';
+
 export type MissionKind = 'plan' | 'build' | 'review' | 'research' | 'quick' | 'vision';
 
 export type MissionAttachmentKind = 'image' | 'audio' | 'video' | 'document';
@@ -211,7 +212,7 @@ function resolveEntry(
   return { provider: DEFAULT_PROVIDER[mission], model: DEFAULT_MODEL[mission] };
 }
 
-/** Tier 2 seam — local LLM classifier (P1-3). When confidence from
+/** Tier 2 seam — injected LLM classifier (P1-3). When confidence from
  *  Tier 1 drops below TIER2_THRESHOLD the router calls this client
  *  to refine the mission with a grammar-constrained 1-token
  *  prediction. Implementations are pluggable — the substrate today
@@ -219,14 +220,18 @@ function resolveEntry(
  *  src/background-reasoning/local-llm-process.ts; a future PR wires
  *  the qwen-2.5 grammar path through.
  *
- *  Contract: respond with one of the 6 MissionKind strings + a
- *  confidence in [0, 1]. Throw on unrecoverable error; the router
+ *  Contract: classify with the supplied classify-role provider/model,
+ *  respond with one of the 6 MissionKind strings + a confidence in [0, 1].
+ *  Throw on unrecoverable error; the router
  *  swallows and falls back to Tier 1. */
 export interface MissionLocalLLMClient {
   classify(input: {
     text: string;
     attachments?: ReadonlyArray<MissionAttachment>;
-  }): Promise<{ mission: MissionKind; confidence: number }>;
+    /** The classify-role selection the client must use. */
+    provider: string;
+    model: string;
+  }): Promise<{ mission: MissionKind; confidence: number; /** The model actually used — must equal the requested one or the decision is discarded. */ model?: string }>;
 }
 
 export const TIER2_CONFIDENCE_THRESHOLD = 0.6;
@@ -320,18 +325,27 @@ export function createMissionRouter(opts?: {
           confidence = cached.confidence;
           tier = 2;
         } else {
-          try {
-            const refined = await localLLM.classify({
-              text: input.text ?? '',
-              attachments: input.attachments,
-            });
-            cache.set(key, refined, now());
-            mission = refined.mission;
-            confidence = refined.confidence;
+          const decision = await judge({
+            site: 'llm.mission-router', prompt: JSON.stringify({ text: input.text ?? '', attachments: input.attachments ?? [] }),
+            call: async ({ provider, model }) => {
+              const refined = await localLLM.classify({ text: input.text ?? '', attachments: input.attachments, provider, model });
+              // Enforce the classify-role model: a client that ignored it (or can't say) doesn't get to decide.
+              return { text: refined.model === model && model ? JSON.stringify(refined) : 'null', modelId: refined.model };
+            },
+            schema: (value) => {
+              if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+              const row = value as Record<string, unknown>;
+              if (typeof row.mission !== 'string' || !Object.hasOwn(DEFAULT_PROVIDER, row.mission) ||
+                  typeof row.confidence !== 'number' || !Number.isFinite(row.confidence) ||
+                  row.confidence < 0 || row.confidence > 1) return null;
+              return { mission: row.mission as MissionKind, confidence: row.confidence };
+            },
+          });
+          if (decision.ok) {
+            cache.set(key, decision.value, now());
+            mission = decision.value.mission;
+            confidence = decision.value.confidence;
             tier = 2;
-          } catch {
-            // Swallow · keep Tier 1 result. classifier hiccup
-            // shouldn't stall the input chip.
           }
         }
       }

package/src/loops/contract/examples/cmo-seat.loop.yaml

@@ -0,0 +1,51 @@
+id: cmo-seat
+version: 1.0.0
+kind: seat
+role: docs/roles/MK.md
+graph: graphs/operate-loop.yaml
+cadence:
+  timezone: Asia/Seoul
+  byDefcon:
+    - {defcon: 5, everyMinutes: 1440}
+    - {defcon: 4, everyMinutes: 720}
+    - {defcon: 3, everyMinutes: 240}
+    - {defcon: 2, everyMinutes: 60}
+    - {defcon: 1, everyMinutes: 15}
+posture:
+  default: 5
+  levels:
+    - {defcon: 5, minResolution: L0, maxResolution: L2, budget: &normal {maxTokens: 6000, maxToolCalls: 6, maxCostUsd: 0.4}}
+    - {defcon: 4, minResolution: L0, maxResolution: L2, budget: *normal}
+    - {defcon: 3, minResolution: L1, maxResolution: L3, budget: &urgent {maxTokens: 12000, maxToolCalls: 12, maxCostUsd: 0.8}}
+    - {defcon: 2, minResolution: L1, maxResolution: L3, budget: *urgent}
+    - {defcon: 1, minResolution: L1, maxResolution: L3, budget: *urgent}
+  raiseOn: [{event: mk-checklist-red-or-request-urgent, afterTicks: 1}]
+  lowerOn: [{event: mk-backlog-clear, afterTicks: 2}]
+  hysteresis: {minDwellMinutes: 120, clearTicks: 2}
+resolution:
+  default: L0
+  steps:
+    - {level: L0, grounding: [], budget: &scan {maxTokens: 1500, maxToolCalls: 2, maxCostUsd: 0.1}}
+    - {level: L1, grounding: [{tool: omni-digest, budget: *scan}], budget: *normal}
+    - {level: L2, grounding: [{tool: omni-crawl, budget: *normal}], budget: *urgent}
+    - {level: L3, grounding: [{tool: social-pulse, budget: *scan}, {tool: aside-repl, budget: *normal}], budget: *urgent}
+  raiseOn: {event: campaign-anomaly, afterTicks: 1}
+  lowerOn: {event: verified-campaign-outcome, afterTicks: 2}
+grounding: [omni-digest, omni-crawl, social-pulse, aside-repl]
+memory:
+  local: {ledger: seat-loop/MK/YYYY-MM-DD.jsonl, working: loop/cmo-seat/context}
+  promotesTo: [self-recall, decisions, checklist]
+  retention: {workingDays: 7, ledgerDays: 90}
+neighbors:
+  - {id: op-seat, exchange: [status, request, decision, blocked], heartbeat: {everyMinutes: 1440, missedTicks: 2}, onAbsent: {action: defer, delegateTo: orchestrator}}
+  - {id: ux-seat, exchange: [status, request, blocked], heartbeat: {everyMinutes: 1440, missedTicks: 2}, onAbsent: {action: defer, delegateTo: orchestrator}}
+  - {id: tc-seat, exchange: [status, request, blocked], heartbeat: {everyMinutes: 1440, missedTicks: 2}, onAbsent: {action: defer, delegateTo: orchestrator}}
+spawn:
+  allowed: [harness]
+  max: 1
+  reap: {afterMinutes: 120, onExit: reconcile}
+hitl: {ladder: [self-heal, neighbor, orchestrator, human]}
+budget: *urgent
+observability:
+  category: loop.cmo-seat
+  events: [tick, posture-change, resolution-change, grounding, heartbeat, absent, exchange, spawn, reap, promote, hitl]

package/src/loops/contract/examples/orchestrator.loop.yaml

@@ -0,0 +1,57 @@
+id: orchestrator
+version: 1.0.0
+kind: orchestrator
+role: docs/roles/OP.md
+graph: graphs/operate-loop.yaml
+orchestration:
+  windows:
+    - {at: '08:00', delegateTo: [op-seat, cmo-seat, tc-seat, ux-seat], fromLedger: release/checklist-and-seat-requests}
+    - {at: '12:00', delegateTo: [op-seat, cmo-seat, tc-seat, ux-seat], fromLedger: seat-loop/status-and-decisions}
+    - {at: '18:00', delegateTo: [op-seat, cmo-seat, tc-seat, ux-seat], fromLedger: release/landings-and-blockers}
+cadence:
+  timezone: Asia/Seoul
+  byDefcon:
+    - {defcon: 5, everyMinutes: 120}
+    - {defcon: 4, everyMinutes: 60}
+    - {defcon: 3, everyMinutes: 30}
+    - {defcon: 2, everyMinutes: 15}
+    - {defcon: 1, everyMinutes: 5}
+posture:
+  default: 5
+  levels:
+    - {defcon: 5, minResolution: L0, maxResolution: L2, budget: &normal {maxTokens: 8000, maxToolCalls: 8, maxCostUsd: 0.5}}
+    - {defcon: 4, minResolution: L0, maxResolution: L2, budget: *normal}
+    - {defcon: 3, minResolution: L1, maxResolution: L3, budget: &urgent {maxTokens: 16000, maxToolCalls: 16, maxCostUsd: 1}}
+    - {defcon: 2, minResolution: L1, maxResolution: L3, budget: *urgent}
+    - {defcon: 1, minResolution: L1, maxResolution: L3, budget: *urgent}
+  raiseOn: [{event: release-red-or-neighbor-blocked, afterTicks: 1}]
+  lowerOn: [{event: all-seats-clear, afterTicks: 2}]
+  hysteresis: {minDwellMinutes: 60, clearTicks: 2}
+resolution:
+  default: L0
+  steps:
+    - {level: L0, grounding: [], budget: &scan {maxTokens: 2000, maxToolCalls: 2, maxCostUsd: 0.1}}
+    - {level: L1, grounding: [{tool: omni-digest, budget: *scan}], budget: *normal}
+    - {level: L2, grounding: [{tool: omni-crawl, budget: *normal}, {tool: aside-repl, budget: *scan}], budget: *urgent}
+    - {level: L3, grounding: [{tool: social-pulse, budget: *scan}, {tool: omni-crawl, budget: *normal}], budget: *urgent}
+  raiseOn: {event: new-anomaly-or-unknown, afterTicks: 1}
+  lowerOn: {event: evidence-stable, afterTicks: 2}
+grounding: [omni-digest, omni-crawl, aside-repl, social-pulse]
+memory:
+  local: {ledger: loop/orchestrator/events, working: loop/orchestrator/context}
+  promotesTo: [self-recall, decisions, checklist]
+  retention: {workingDays: 7, ledgerDays: 90}
+neighbors:
+  - {id: op-seat, exchange: [status, request, decision, blocked], heartbeat: {everyMinutes: 120, missedTicks: 2}, onAbsent: {action: delegate, delegateTo: steward}}
+  - {id: cmo-seat, exchange: [status, request, blocked], heartbeat: {everyMinutes: 120, missedTicks: 2}, onAbsent: {action: defer, delegateTo: orchestrator}}
+  - {id: tc-seat, exchange: [status, request, blocked], heartbeat: {everyMinutes: 120, missedTicks: 2}, onAbsent: {action: escalate, delegateTo: orchestrator}}
+  - {id: ux-seat, exchange: [status, request, blocked], heartbeat: {everyMinutes: 120, missedTicks: 2}, onAbsent: {action: defer, delegateTo: orchestrator}}
+spawn:
+  allowed: [agent, harness]
+  max: 4
+  reap: {afterMinutes: 120, onExit: reconcile}
+hitl: {ladder: [self-heal, neighbor, orchestrator, human]}
+budget: *urgent
+observability:
+  category: loop.orchestrator
+  events: [tick, posture-change, resolution-change, grounding, heartbeat, absent, exchange, spawn, reap, promote, hitl]

package/src/loops/contract/examples/steward.loop.yaml

@@ -0,0 +1,50 @@
+id: steward
+version: 1.0.0
+kind: function
+role: steward-intake-triage-schedule-report
+graph: graphs/steward/steward.yaml
+cadence:
+  timezone: Asia/Seoul
+  byDefcon:
+    - {defcon: 5, everyMinutes: 15}
+    - {defcon: 4, everyMinutes: 15}
+    - {defcon: 3, everyMinutes: 10}
+    - {defcon: 2, everyMinutes: 5}
+    - {defcon: 1, everyMinutes: 2}
+posture:
+  default: 5
+  levels:
+    - {defcon: 5, minResolution: L0, maxResolution: L2, budget: &normal {maxTokens: 5000, maxToolCalls: 5, maxCostUsd: 0.3}}
+    - {defcon: 4, minResolution: L0, maxResolution: L2, budget: *normal}
+    - {defcon: 3, minResolution: L1, maxResolution: L3, budget: &urgent {maxTokens: 10000, maxToolCalls: 10, maxCostUsd: 0.6}}
+    - {defcon: 2, minResolution: L1, maxResolution: L3, budget: *urgent}
+    - {defcon: 1, minResolution: L1, maxResolution: L3, budget: *urgent}
+  raiseOn: [{event: directive-urgent-or-stalled-task, afterTicks: 1}]
+  lowerOn: [{event: backlog-reconciled, afterTicks: 2}]
+  hysteresis: {minDwellMinutes: 30, clearTicks: 2}
+resolution:
+  default: L0
+  steps:
+    - {level: L0, grounding: [], budget: &scan {maxTokens: 1200, maxToolCalls: 2, maxCostUsd: 0.1}}
+    - {level: L1, grounding: [{tool: omni-digest, budget: *scan}], budget: *normal}
+    - {level: L2, grounding: [{tool: omni-crawl, budget: *normal}], budget: *urgent}
+    - {level: L3, grounding: [{tool: aside-repl, budget: *normal}], budget: *urgent}
+  raiseOn: {event: unknown-owner-or-failed-reconcile, afterTicks: 1}
+  lowerOn: {event: ledger-reconciled, afterTicks: 2}
+grounding: [omni-digest, omni-crawl, aside-repl]
+memory:
+  local: {ledger: loop/steward/events, working: loop/steward/context}
+  promotesTo: [self-recall, decisions, checklist]
+  retention: {workingDays: 7, ledgerDays: 90}
+neighbors:
+  - {id: orchestrator, exchange: [status, request, decision, blocked], heartbeat: {everyMinutes: 120, missedTicks: 2}, onAbsent: {action: escalate, delegateTo: human}}
+  - {id: op-seat, exchange: [status, request, blocked], heartbeat: {everyMinutes: 120, missedTicks: 2}, onAbsent: {action: defer, delegateTo: orchestrator}}
+spawn:
+  allowed: [agent, harness]
+  max: 2
+  reap: {afterMinutes: 120, onExit: reconcile}
+hitl: {ladder: [self-heal, neighbor, orchestrator, human]}
+budget: *urgent
+observability:
+  category: loop.steward
+  events: [tick, posture-change, resolution-change, grounding, heartbeat, absent, exchange, spawn, reap, promote, hitl]

package/src/loops/contract/loop-agent.schema.json

@@ -0,0 +1,138 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://elanous.ai/schemas/loop-agent/1.0.0",
+  "title": "Loop agent manifest v1 (design contract; not an execution graph)",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["id", "version", "kind", "role", "graph", "cadence", "posture", "resolution", "grounding", "memory", "neighbors", "spawn", "hitl", "budget", "observability"],
+  "properties": {
+    "id": { "type": "string", "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$" },
+    "version": { "type": "string", "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$" },
+    "kind": { "enum": ["orchestrator", "seat", "function", "external"] },
+    "role": { "type": "string", "minLength": 1 },
+    "graph": { "type": "string", "pattern": "^graphs/[a-zA-Z0-9/_-]+\\.yaml$" },
+    "orchestration": { "type": "object", "additionalProperties": false, "required": ["windows"], "properties": {
+      "windows": { "type": "array", "minItems": 1, "items": { "type": "object", "additionalProperties": false,
+        "required": ["at", "delegateTo", "fromLedger"], "properties": {
+          "at": { "type": "string", "pattern": "^(?:[01][0-9]|2[0-3]):[0-5][0-9]$" },
+          "delegateTo": { "type": "array", "minItems": 1, "uniqueItems": true,
+            "items": { "enum": ["op-seat", "cmo-seat", "tc-seat", "ux-seat"] } },
+          "fromLedger": { "type": "string", "minLength": 1 }
+        }
+      } }
+    } },
+    "cadence": {
+      "description": "Each DEFCON profile specifies a tick interval in minutes; existing cron remains authoritative until migration.",
+      "type": "object", "additionalProperties": false,
+      "required": ["timezone", "byDefcon"],
+      "properties": {
+        "timezone": { "type": "string", "minLength": 1 },
+        "byDefcon": { "type": "array", "minItems": 5, "maxItems": 5, "prefixItems": [
+          { "$ref": "#/$defs/cadence5" }, { "$ref": "#/$defs/cadence4" }, { "$ref": "#/$defs/cadence3" }, { "$ref": "#/$defs/cadence2" }, { "$ref": "#/$defs/cadence1" }
+        ] }
+      }
+    },
+    "posture": {
+      "type": "object", "additionalProperties": false,
+      "required": ["default", "levels", "raiseOn", "lowerOn", "hysteresis"],
+      "properties": {
+        "default": { "type": "integer", "minimum": 1, "maximum": 5 },
+        "levels": { "type": "array", "minItems": 5, "maxItems": 5, "prefixItems": [
+          { "$ref": "#/$defs/posture5" }, { "$ref": "#/$defs/posture4" }, { "$ref": "#/$defs/posture3" }, { "$ref": "#/$defs/posture2" }, { "$ref": "#/$defs/posture1" }
+        ] },
+        "raiseOn": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/signal" } },
+        "lowerOn": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/signal" } },
+        "hysteresis": { "type": "object", "additionalProperties": false, "required": ["minDwellMinutes", "clearTicks"], "properties": {
+          "minDwellMinutes": { "type": "integer", "minimum": 1 }, "clearTicks": { "type": "integer", "minimum": 2 }
+        } }
+      }
+    },
+    "resolution": {
+      "description": "Local depth rises L0→L3; the posture profile bounds it, independently of DEFCON direction.",
+      "type": "object", "additionalProperties": false, "required": ["default", "steps", "raiseOn", "lowerOn"],
+      "properties": {
+        "default": { "enum": ["L0", "L1", "L2", "L3"] },
+        "steps": { "type": "array", "minItems": 4, "maxItems": 4, "prefixItems": [
+          { "$ref": "#/$defs/resolution0" }, { "$ref": "#/$defs/resolution1" }, { "$ref": "#/$defs/resolution2" }, { "$ref": "#/$defs/resolution3" }
+        ] },
+        "raiseOn": { "$ref": "#/$defs/signal" }, "lowerOn": { "$ref": "#/$defs/signal" }
+      }
+    },
+    "grounding": { "type": "array", "uniqueItems": true, "items": { "enum": ["omni-crawl", "omni-digest", "aside-repl", "social-pulse"] } },
+    "memory": { "type": "object", "additionalProperties": false, "required": ["local", "promotesTo", "retention"], "properties": {
+      "local": { "type": "object", "additionalProperties": false, "required": ["ledger", "working"], "properties": {
+        "ledger": { "type": "string", "minLength": 1 }, "working": { "type": "string", "minLength": 1 }
+      } },
+      "promotesTo": { "type": "array", "uniqueItems": true, "items": { "enum": ["self-recall", "decisions", "checklist"] } },
+      "retention": { "type": "object", "additionalProperties": false, "required": ["workingDays", "ledgerDays"], "properties": {
+        "workingDays": { "type": "integer", "minimum": 1 }, "ledgerDays": { "type": "integer", "minimum": 1 }
+      } }
+    } },
+    "neighbors": { "type": "array", "items": { "$ref": "#/$defs/neighbor" } },
+    "spawn": { "type": "object", "additionalProperties": false, "required": ["allowed", "max", "reap"], "properties": {
+      "allowed": { "type": "array", "uniqueItems": true, "items": { "enum": ["agent", "harness"] } },
+      "max": { "type": "integer", "minimum": 0 },
+      "reap": { "type": "object", "additionalProperties": false, "required": ["afterMinutes", "onExit"], "properties": {
+        "afterMinutes": { "type": "integer", "minimum": 1 }, "onExit": { "enum": ["reconcile", "escalate"] }
+      } }
+    } },
+    "hitl": { "type": "object", "additionalProperties": false, "required": ["ladder"], "properties": {
+      "ladder": { "const": ["self-heal", "neighbor", "orchestrator", "human"] }
+    } },
+    "budget": { "$ref": "#/$defs/budget" },
+    "observability": { "type": "object", "additionalProperties": false, "required": ["category", "events"], "properties": {
+      "category": { "type": "string", "pattern": "^loop\\.[a-z][a-z0-9]*(?:-[a-z0-9]+)*$" },
+      "events": { "type": "array", "uniqueItems": true, "minItems": 1, "items": { "enum": ["tick", "posture-change", "resolution-change", "grounding", "heartbeat", "absent", "exchange", "spawn", "reap", "promote", "hitl"] } }
+    } }
+  },
+  "allOf": [{ "if": { "properties": { "kind": { "const": "orchestrator" } }, "required": ["kind"] }, "then": { "properties": { "orchestration": true }, "required": ["orchestration"] }, "else": { "not": { "required": ["orchestration"] } } }],
+  "$defs": {
+    "budget": { "type": "object", "additionalProperties": false, "required": ["maxTokens", "maxToolCalls", "maxCostUsd"], "properties": {
+      "maxTokens": { "type": "integer", "minimum": 1 }, "maxToolCalls": { "type": "integer", "minimum": 1 }, "maxCostUsd": { "type": "number", "exclusiveMinimum": 0 }
+    } },
+    "groundingCall": { "type": "object", "additionalProperties": false, "required": ["tool", "budget"], "properties": {
+      "tool": { "enum": ["omni-crawl", "omni-digest", "aside-repl", "social-pulse"] },
+      "budget": { "$ref": "#/$defs/budget" }
+    } },
+    "resolutionStep": { "type": "object", "additionalProperties": false, "required": ["level", "grounding", "budget"], "properties": {
+      "level": { "enum": ["L0", "L1", "L2", "L3"] },
+      "grounding": { "type": "array", "items": { "$ref": "#/$defs/groundingCall" } },
+      "budget": { "$ref": "#/$defs/budget" }
+    } },
+    "resolution0": { "allOf": [{ "$ref": "#/$defs/resolutionStep" }, { "type": "object", "properties": { "level": { "const": "L0" } } }] },
+    "resolution1": { "allOf": [{ "$ref": "#/$defs/resolutionStep" }, { "type": "object", "properties": { "level": { "const": "L1" } } }] },
+    "resolution2": { "allOf": [{ "$ref": "#/$defs/resolutionStep" }, { "type": "object", "properties": { "level": { "const": "L2" } } }] },
+    "resolution3": { "allOf": [{ "$ref": "#/$defs/resolutionStep" }, { "type": "object", "properties": { "level": { "const": "L3" } } }] },
+    "signal": { "type": "object", "additionalProperties": false, "required": ["event", "afterTicks"], "properties": {
+      "event": { "type": "string", "minLength": 1 }, "afterTicks": { "type": "integer", "minimum": 1 }
+    } },
+    "cadenceStep": { "type": "object", "additionalProperties": false, "required": ["defcon", "everyMinutes"], "properties": {
+      "defcon": { "type": "integer", "minimum": 1, "maximum": 5 }, "everyMinutes": { "type": "integer", "minimum": 1 }
+    } },
+    "cadence5": { "allOf": [{ "$ref": "#/$defs/cadenceStep" }, { "type": "object", "properties": { "defcon": { "const": 5 } } }] },
+    "cadence4": { "allOf": [{ "$ref": "#/$defs/cadenceStep" }, { "type": "object", "properties": { "defcon": { "const": 4 } } }] },
+    "cadence3": { "allOf": [{ "$ref": "#/$defs/cadenceStep" }, { "type": "object", "properties": { "defcon": { "const": 3 } } }] },
+    "cadence2": { "allOf": [{ "$ref": "#/$defs/cadenceStep" }, { "type": "object", "properties": { "defcon": { "const": 2 } } }] },
+    "cadence1": { "allOf": [{ "$ref": "#/$defs/cadenceStep" }, { "type": "object", "properties": { "defcon": { "const": 1 } } }] },
+    "postureStep": { "type": "object", "additionalProperties": false, "required": ["defcon", "minResolution", "maxResolution", "budget"], "properties": {
+      "defcon": { "type": "integer", "minimum": 1, "maximum": 5 }, "minResolution": { "enum": ["L0", "L1", "L2", "L3"] },
+      "maxResolution": { "enum": ["L0", "L1", "L2", "L3"] }, "budget": { "$ref": "#/$defs/budget" }
+    } },
+    "posture5": { "allOf": [{ "$ref": "#/$defs/postureStep" }, { "type": "object", "properties": { "defcon": { "const": 5 } } }] },
+    "posture4": { "allOf": [{ "$ref": "#/$defs/postureStep" }, { "type": "object", "properties": { "defcon": { "const": 4 } } }] },
+    "posture3": { "allOf": [{ "$ref": "#/$defs/postureStep" }, { "type": "object", "properties": { "defcon": { "const": 3 } } }] },
+    "posture2": { "allOf": [{ "$ref": "#/$defs/postureStep" }, { "type": "object", "properties": { "defcon": { "const": 2 } } }] },
+    "posture1": { "allOf": [{ "$ref": "#/$defs/postureStep" }, { "type": "object", "properties": { "defcon": { "const": 1 } } }] },
+    "neighbor": { "type": "object", "additionalProperties": false, "required": ["id", "exchange", "heartbeat", "onAbsent"], "properties": {
+      "id": { "type": "string", "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$" },
+      "exchange": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "enum": ["status", "request", "decision", "blocked"] } },
+      "heartbeat": { "type": "object", "additionalProperties": false, "required": ["everyMinutes", "missedTicks"], "properties": {
+        "everyMinutes": { "type": "integer", "minimum": 1 }, "missedTicks": { "type": "integer", "minimum": 1 }
+      } },
+      "onAbsent": { "type": "object", "additionalProperties": false, "required": ["action", "delegateTo"], "properties": {
+        "action": { "enum": ["delegate", "defer", "escalate"] },
+        "delegateTo": { "type": "string", "minLength": 1 }
+      } }
+    } }
+  }
+}

package/src/loops/contract/validate.ts

@@ -0,0 +1,64 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import Ajv2020 from 'ajv/dist/2020.js';
+import { parse as parseYaml } from 'yaml';
+
+const schema = JSON.parse(readFileSync(resolve(import.meta.dir, 'loop-agent.schema.json'), 'utf8'));
+const ajv = new Ajv2020({ allErrors: true, strict: true });
+const validateShape = ajv.compile(schema);
+const resolutionRank: Record<string, number> = { L0: 0, L1: 1, L2: 2, L3: 3 };
+
+type LoopManifest = {
+  id: string;
+  grounding: string[];
+  posture: { levels: { minResolution: string; maxResolution: string }[] };
+  resolution: { steps: { grounding: { tool: string }[] }[] };
+  observability: { category: string };
+};
+
+/** Run on the complete manifest, including the final result of any overlay merge. */
+export function loopAgentContractErrors(input: unknown): string[] {
+  if (!validateShape(input)) {
+    return (validateShape.errors ?? []).map(error => `${error.instancePath} ${error.message}`);
+  }
+  const doc = input as LoopManifest;
+  const errors: string[] = [];
+  if (doc.observability.category !== `loop.${doc.id}`) {
+    errors.push('observability.category must equal loop.<id>');
+  }
+  for (const [index, profile] of doc.posture.levels.entries()) {
+    if (resolutionRank[profile.minResolution]! > resolutionRank[profile.maxResolution]!) {
+      errors.push(`/posture/levels/${index} resolution bounds reversed`);
+    }
+  }
+  const tools = new Set(doc.grounding);
+  for (const [stepIndex, step] of doc.resolution.steps.entries()) {
+    for (const [callIndex, call] of step.grounding.entries()) {
+      if (!tools.has(call.tool)) {
+        errors.push(`/resolution/steps/${stepIndex}/grounding/${callIndex} undeclared grounding tool: ${call.tool}`);
+      }
+    }
+  }
+  return errors;
+}
+
+if (import.meta.main) {
+  const path = process.argv[2];
+  if (!path || process.argv.length !== 3) {
+    console.error('usage: bun src/loops/contract/validate.ts <merged-manifest.yaml|->');
+    process.exitCode = 2;
+  } else {
+    try {
+      const errors = loopAgentContractErrors(parseYaml(readFileSync(path === '-' ? 0 : path, 'utf8')));
+      if (errors.length) {
+        console.error(errors.join('\n'));
+        process.exitCode = 1;
+      } else {
+        console.log('loop-agent contract valid');
+      }
+    } catch (error) {
+      console.error(error);
+      process.exitCode = 1;
+    }
+  }
+}

package/src/loops/registry.ts

@@ -24,7 +24,7 @@ export interface LoopEntry {
   description: string | null;
   file: string;
   trigger: { cron: string | null; events: string[] };
-  jobs: Array<{ id: string; cron: string | null; enabled: boolean }>;
+  jobs: Array<{ id: string; cron: string | null; enabled: boolean; entryScript?: boolean }>;
   enabled: boolean;
   lastRun: LoopRun | null;
   nextRun: string | null;
@@ -63,6 +63,14 @@ export function graphJobMatches(command: string | null, file: string, root: stri
   return false;
 }
 
+/** `cron_entry` identifies the script actually launched by cron, not text in another command's arguments. */
+function cronEntryMatches(command: string | null, entry: string): boolean {
+  if (!command) return false;
+  const invocation = command.match(/^(?:cd\s+\S+\s*&&\s*)?(?:(?:\S*\/)?(?:bun|node)\s+\S*cron-run\.ts\s+--schedule-id\s+\S+\s+--shell\s+)?(?:(?:\S*\/)?(?:bash|zsh|sh)\s+)?(['"]?)([^\s'";&|]+\.sh)\1(?=\s|$|[;&|])/);
+  const script = invocation?.[2];
+  return !!script && (script === entry || script.endsWith(`/${entry}`));
+}
+
 function recentRuns(id: string, stateRoot: string, count = 5): LoopRun[] {
   const dir = join(stateRoot, 'graph-runs', id);
   let files: string[];
@@ -130,11 +138,15 @@ export function listLoops(opts: LoopRegistryOptions = {}): LoopEntry[] {
     const trigger = header?.trigger && typeof header.trigger === 'object' && !Array.isArray(header.trigger) ? header.trigger as Record<string, unknown> : null;
     const declaredCron = typeof trigger?.cron === 'string' ? trigger.cron : null;
     const events = Array.isArray(trigger?.events) ? trigger.events.filter((e): e is string => typeof e === 'string') : [];
-    const matched = rows.filter(row => graphJobMatches(row.command, file, root, doc.graph_id as string) && row.source === 'crontab' && row.run_via === 'crontab' && row.disabled_reason !== 'vanished');
+    const cronEntry = typeof doc.cron_entry === 'string' && doc.cron_entry.length ? doc.cron_entry : null;
+    const entryRows = cronEntry ? rows.filter(row => cronEntryMatches(row.command, cronEntry) && row.source === 'crontab' && row.run_via === 'crontab' && row.disabled_reason !== 'vanished') : [];
+    const matched = rows.filter(row => (graphJobMatches(row.command, file, root, doc.graph_id as string) || entryRows.includes(row)) && row.source === 'crontab' && row.run_via === 'crontab' && row.disabled_reason !== 'vanished');
+    if (entryRows.length) debug.log('loops.registry', 'cron-entry-match', { id: doc.graph_id, jobs: entryRows.map(row => row.id) });
     if (!declaredCron && !events.length && !matched.length) continue;
     if (!/^[a-zA-Z0-9][\w.-]*$/.test(doc.graph_id)) throw new Error(`unsafe loop graph_id: ${doc.graph_id}`);
     if (loops.some(loop => loop.id === doc.graph_id)) throw new Error(`duplicate loop graph_id: ${doc.graph_id}`);
-    const jobs = matched.map(row => ({ id: row.id, cron: row.cron, enabled: !!row.enabled }));
+    const jobs = matched.map(row => ({ id: row.id, cron: row.cron, enabled: !!row.enabled,
+      ...(entryRows.includes(row) ? { entryScript: true } : {}) }));
     const active = matched.filter(row => !!row.enabled && !!row.cron);
     const next = active.map(row => nextLoopFire(row.cron!, opts.now ?? new Date())).filter((v): v is string => v !== null).sort()[0] ?? null;
     const entry: LoopEntry = { id: doc.graph_id, title: typeof header?.title === 'string' ? header.title : doc.graph_id,
@@ -169,10 +181,12 @@ export async function setLoopEnabled(id: string, enabled: boolean, yes = false,
   const action = enabled ? 'start' : 'stop';
   if (!loop.jobs.length && (!enabled || !loop.trigger.cron)) throw new Error(`loop ${id} has no cron job to ${action}`);
   const pending = loop.jobs.filter(job => job.enabled !== enabled);
-  if (!pending.length && loop.jobs.length) return { action, id, changed: false, enabled: loop.enabled };
+  const entryScript = loop.jobs.some(job => job.entryScript);
+  const entryLabel = entryScript ? { entryScript: true } : {};
+  if (!pending.length && loop.jobs.length) return { action, id, changed: false, enabled: loop.enabled, ...entryLabel };
   const changes = loop.jobs.length ? pending.map(job => ({ action: enabled ? 'enable' : 'disable', id: job.id })) :
     [{ action: 'create', cron: loop.trigger.cron, command: loopCronCommand(id, loop.file, resolve(opts.root ?? defaultLoopRoot())) }];
-  if (!yes) return { action, id, dryRun: true, changes, note: 'Apply with --yes (crontab backup).' };
+  if (!yes) return { action, id, dryRun: true, changes, ...entryLabel, note: 'Apply with --yes (crontab backup).' };
   const dispatch = opts.scheduleAction ?? (async (kind: 'create' | 'enable' | 'disable', args: Record<string, unknown>) => {
     const { dispatchScheduleManage } = await import('../domains/schedule-manage-tool.js');
     return dispatchScheduleManage({ action: kind, ...args });
@@ -186,7 +200,7 @@ export async function setLoopEnabled(id: string, enabled: boolean, yes = false,
   }
   debug.log('loops.registry', action, { id, changes });
   emitDecision({ kind: 'ROUTE', what: `루프 ${enabled ? '켬' : '끔'}: ${id}`, reason: enabled ? '사용자 요청으로 예약 발화 활성화' : '사용자 요청으로 예약 발화 일시 중지', purpose: '루프 라이프사이클 제어', target: id });
-  return { action, id, changed: true, results };
+  return { action, id, changed: true, results, ...entryLabel };
 }
 
 export async function runLoop(id: string, dryRun = false, opts: LoopRegistryOptions = {}): Promise<GraphRunState> {

package/src/market/signed-index.ts

@@ -91,6 +91,10 @@ function invalidIndex(value: unknown): string | null {
   return null;
 }
 
+export function validateMarketplaceIndex(value: unknown): string | null {
+  return invalidIndex(value);
+}
+
 export function verifyIndex(input: {
   marketplaceBytes: Uint8Array;
   signatureText: string;

package/src/maturity/bot-command-maturity.ts

@@ -0,0 +1,45 @@
+import { getUserConfig } from '../user-config.js';
+import { FEATURE_MATURITY, type Role } from './feature-maturity.js';
+
+export type BotSurface = 'telegram' | 'discord';
+export type BotAudience = { role: Role; showBeta: boolean };
+
+/** The menu audience is independent of the inbound command authorization gate. */
+export function readBotAudience(raw: unknown = undefined): BotAudience {
+  const value = raw && typeof raw === 'object' && !Array.isArray(raw) ? raw as Record<string, unknown> : {};
+  const role = value.role === 'general' || value.role === 'contributor' || value.role === 'owner' ? value.role : 'owner';
+  return { role, showBeta: value.showBeta === true };
+}
+
+export function botAudienceFor(surface: BotSurface): BotAudience {
+  const raw = getUserConfig().raw?.[surface] as { commandAudience?: unknown } | undefined;
+  return readBotAudience(raw?.commandAudience);
+}
+
+export function botCommandVisible(surface: BotSurface, name: string, role: Role, { showBeta }: { showBeta: boolean }): boolean {
+  const grades: Record<string, string> = surface === 'telegram' ? FEATURE_MATURITY.telegramCommand : FEATURE_MATURITY.discordCommand;
+  const grade = Object.hasOwn(grades, name) ? grades[name] : undefined;
+  if (!grade) return role === 'owner';
+  if (role === 'owner') return true;
+  if (grade === 'stable') return true;
+  if (role === 'contributor') return grade === 'beta' || grade === 'tool';
+  return grade === 'beta' && showBeta;
+}
+
+export function filterBotCommands<T extends { name: string }>(surface: BotSurface, names: readonly T[], audience: BotAudience): T[] {
+  return names.filter(({ name }) => botCommandVisible(surface, name, audience.role, audience));
+}
+
+/** Discord can only invoke registered slash commands, so hiding must not unregister them.
+ *  Every schema stays registered; ones hidden for this audience become admin-only
+ *  (`default_member_permissions: "0"`), which removes them from members' pickers while
+ *  server admins (the owner) can still call them. An explicit permission on a schema wins. */
+export function gateDiscordSchemas<T extends { name: string; defaultMemberPermissions?: string }>(schemas: readonly T[], audience: BotAudience): { schemas: T[]; hidden: number } {
+  let hidden = 0;
+  const out = schemas.map((schema) => {
+    if (botCommandVisible('discord', schema.name, audience.role, audience) || schema.defaultMemberPermissions !== undefined) return schema;
+    hidden++;
+    return { ...schema, defaultMemberPermissions: '0' };
+  });
+  return { schemas: out, hidden };
+}