elanous 0.2.9 → 0.2.11

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 };
+}

package/src/maturity/cli-maturity.ts

@@ -0,0 +1,34 @@
+import type { Command } from 'commander';
+import { program } from '../index.js';
+import { FEATURE_MATURITY, type Maturity, type Role } from './feature-maturity.js';
+
+/** Commander owns aliases; the table contains canonical command names only. */
+export function cliRootMaturity(name: string, commands: readonly Command[] = program.commands): Maturity | undefined {
+  const command = commands.find((entry) => entry.name() === name || entry.aliases().includes(name));
+  const canonical = command?.name() ?? name;
+  return Object.prototype.hasOwnProperty.call(FEATURE_MATURITY.cliRoot, canonical)
+    ? FEATURE_MATURITY.cliRoot[canonical as keyof typeof FEATURE_MATURITY.cliRoot]
+    : undefined;
+}
+
+export function cliRootVisibleFor(name: string, role: Role, { showAll }: { showAll: boolean }, commands: readonly Command[] = program.commands): boolean {
+  const grade = cliRootMaturity(name, commands);
+  if (!grade || grade === 'system') return false;
+  if (showAll || role === 'owner') return true;
+  return grade === 'stable' || (role === 'contributor' && (grade === 'beta' || grade === 'tool'));
+}
+
+/** Only help is filtered: Commander still dispatches explicitly typed commands. */
+export function filterCliRootHelp(commands: readonly Command[], role: Role, showAll: boolean): { shown: number; hidden: number } {
+  let shown = 0;
+  let hidden = 0;
+  for (const command of commands) {
+    const grade = cliRootMaturity(command.name(), commands);
+    if (!grade) throw new Error(`cliRoot 에 등급 없는 명령: ${command.name()}`);
+    const visible = cliRootVisibleFor(command.name(), role, { showAll }, commands);
+    (command as Command & { _hidden: boolean })._hidden = !visible;
+    if (visible) shown++;
+    else hidden++;
+  }
+  return { shown, hidden };
+}

package/src/maturity/feature-maturity.ts

@@ -13,6 +13,7 @@ export const FEATURE_MATURITY = {
     '/setup/done': { pwa: 'stable' },
     '/consult': { pwa: 'stable' },
     '/chat': { pwa: 'stable' },
+    '/today': { pwa: 'stable' },
     '/term': { pwa: 'stable' },
     '/live': { pwa: 'stable' },
     '/market': { pwa: 'stable' },
@@ -21,6 +22,7 @@ export const FEATURE_MATURITY = {
     '/editor': { pwa: 'beta' },
     '/intake': { pwa: 'beta' },
     '/trace': { pwa: 'beta' },
+    '/inside': { pwa: 'beta' },
     '/board': { pwa: 'beta' },
     '/autopilot': { pwa: 'beta' },
     '/missions/[id]': { pwa: 'beta' },
@@ -30,6 +32,7 @@ export const FEATURE_MATURITY = {
     '/vault': { pwa: 'beta' },
     '/observatory': { pwa: 'beta' },
     '/exec': { pwa: 'beta' },
+    '/outputs': { pwa: 'beta' },
     '/field': { pwa: 'beta' },
     '/showroom': { pwa: 'beta' },
     '/workflows': { pwa: 'beta' },
@@ -39,6 +42,7 @@ export const FEATURE_MATURITY = {
     '/control': { pwa: 'tool' },
     '/scheduler': { pwa: 'ops' },
     '/ops/release': { pwa: 'ops' },
+    '/ops/seats': { pwa: 'ops' },
     '/ops/checklist': { pwa: 'ops' },
     '/dashboard': { pwa: 'ops' },
     '/bots': { pwa: 'ops' },
@@ -48,7 +52,121 @@ export const FEATURE_MATURITY = {
     '/workflows/chat-ui': { pwa: 'broken' },
     '/share': { pwa: 'system' },
   },
-} as const satisfies { pwaRoute: Record<string, SurfaceMaturity> };
+  // Canonical CLI command names only; aliases inherit their command's grade.
+  cliRoot: {
+    pty: 'beta', pr: 'beta', repo: 'beta', role: 'beta', machine: 'beta',
+    where: 'stable', shadow: 'beta', llm: 'beta', storage: 'beta', leader: 'beta',
+    pod: 'beta', browser: 'beta', questions: 'beta', usage: 'stable', live: 'beta',
+    research: 'beta', release: 'beta', seat: 'beta', coord: 'beta', context: 'beta', 'model-watch': 'beta', doctor: 'stable',
+    control: 'beta', resources: 'beta', hooks: 'beta', setup: 'stable', start: 'stable',
+    grounding: 'beta', graph: 'beta', loop: 'stable', card: 'stable', 'launch-head': 'beta',
+    a2a: 'beta', plugin: 'stable', make: 'beta', skills: 'beta', connect: 'beta', import: 'beta',
+    persona: 'beta', 'team-set': 'beta', market: 'beta', directive: 'stable', connector: 'beta', storyboard: 'beta',
+    python: 'beta', 'self-update': 'stable', 'measure-fabric-arc-ab': 'beta', mcp: 'beta',
+    relay: 'beta', 'telegram-test': 'beta', telegram: 'beta', 'discord-test': 'beta',
+    sync: 'beta', status: 'beta', git: 'beta', gh: 'beta', repro: 'system',
+    theme: 'beta', history: 'beta', inspect: 'beta', autopilot: 'beta', memory: 'beta',
+    decide: 'beta', 'ax-screen': 'beta', 'decide-recipe': 'beta', signals: 'beta',
+    loops: 'beta', buzz: 'beta', harness: 'stable', self: 'beta', factcheck: 'beta',
+    provider: 'stable', 'provider:set': 'beta', 'provider:restore': 'beta',
+    'provider:rotate': 'beta', 'provider:use': 'beta', 'status-bar': 'beta',
+    schedule: 'beta', intake: 'beta', logs: 'stable', ad: 'beta', docs: 'beta',
+    decisions: 'beta', directives: 'beta', fleet: 'beta', ops: 'stable', publish: 'beta',
+    env: 'beta', 'agent-mission': 'beta', dev: 'beta', keys: 'beta', finance: 'beta',
+    config: 'stable', tasks: 'stable', labels: 'beta', msg: 'beta', ask: 'stable',
+    onboarding: 'beta', login: 'stable', session: 'beta', chat: 'stable', repl: 'stable',
+    agent: 'stable', registry: 'beta', tier: 'stable', local: 'beta', scheduler: 'beta',
+    attach: 'beta', wf: 'beta', nexus: 'stable', phone: 'beta', token: 'beta',
+    acp: 'beta', voice: 'beta',
+    'run-detached': 'system', dogfood: 'system', run: 'system',
+  },
+  // Canonical names only; aliases inherit their command's grade at lookup.
+  // Count: bun -e "import('./src/maturity/feature-maturity.ts').then(m=>console.log(Object.keys(m.FEATURE_MATURITY.tuiSlash).length))" (= SLASH_COMMANDS canonical names).
+  tuiSlash: {
+    help: 'stable',
+    resume: 'stable',
+    model: 'stable',
+    clear: 'stable',
+    status: 'stable',
+    now: 'beta', // CTX2 «지금 무엇이 돌고 있나» (#23379)
+    remaining: 'stable',
+    setup: 'stable',
+    quit: 'stable',
+    'run-skill': 'stable',
+    ad: 'beta',
+    design: 'beta',
+    provider: 'stable',
+    reasoning: 'stable',
+    local: 'tool',
+    session: 'stable',
+    fork: 'stable',
+    rewind: 'stable',
+    mission: 'beta',
+    'resume-turn': 'beta',
+    context: 'stable',
+    paste: 'stable',
+    sync: 'tool',
+    plugin: 'tool',
+    widget: 'tool',
+    log: 'tool',
+    memory: 'beta',
+    export: 'stable',
+    delta: 'tool',
+    theme: 'stable',
+    debug: 'tool',
+    rebind: 'tool',
+    'api-allow': 'tool',
+    prompt: 'beta',
+    history: 'stable',
+    research: 'beta',
+    harness: 'ops',
+    plan: 'beta',
+    chat: 'stable',
+    dashboard: 'stable',
+    telegram: 'ops',
+    tablet: 'ops',
+    surface: 'ops',
+    term: 'tool',
+    claude: 'tool',
+    codex: 'tool',
+    gemini: 'tool',
+    acp: 'beta',
+    conv: 'beta',
+    handoff: 'ops',
+    'agent-room': 'ops',
+    showroom: 'ops',
+    reply: 'ops',
+    capture: 'ops',
+    inject: 'ops',
+    relay: 'ops',
+    lane: 'ops',
+    control: 'ops',
+    default: 'ops',
+    qc: 'ops',
+    'voice-chat': 'beta',
+    'auto-tts': 'beta',
+    directive: 'ops',
+  },
+  telegramCommand: {
+    help: 'stable', status: 'stable', new: 'stable', clear: 'stable', reset: 'stable',
+    ping: 'stable', provider: 'stable', sessions: 'stable', fork: 'stable', resume: 'stable',
+    decisions: 'stable', work: 'stable', cancel: 'stable',
+    skills: 'beta', skill: 'beta', digest: 'beta', intake: 'beta', ad: 'beta',
+    taste: 'beta', missions: 'beta', attach: 'beta', detach: 'beta', now: 'beta', project: 'beta',
+    brain: 'tool', cc: 'tool', cdx: 'tool', gem: 'tool', local: 'tool',
+    harness: 'ops',
+    // Existing commands outside the CXO four-grade menu list are owner-only.
+    cc_clear: 'system', coo: 'system', cto: 'system', cmo: 'system', cxo: 'system', mission_del: 'system',
+    bots: 'system', bot: 'system', screen: 'system', chart: 'system', routines: 'system', botsay: 'system',
+  },
+  discordCommand: {
+    status: 'stable', sessions: 'stable', new: 'stable', fork: 'stable',
+    persona: 'beta', poll: 'beta', attach: 'beta',
+    brain: 'tool', cc: 'tool', cdx: 'tool', gem: 'tool',
+    relay: 'ops', showroom: 'ops', bots: 'ops', bot: 'ops', screen: 'ops', chart: 'ops',
+    routines: 'ops', botsay: 'ops', 'voice-join': 'ops', 'voice-leave': 'ops', 'voice-status': 'ops',
+  },
+} as const satisfies { pwaRoute: Record<string, SurfaceMaturity>; cliRoot: Record<string, Maturity>; tuiSlash: Record<string, Maturity>; telegramCommand: Record<string, Maturity>; discordCommand: Record<string, Maturity> };
 
 /** Unregistered routes and surfaces are not implicitly mature. Desktop shares the PWA implementation. */
 export function maturityOn(route: string, surface: Surface): Maturity | undefined {
@@ -65,3 +183,4 @@ export function visibleOn(route: string, surface: Surface, role: Role): boolean
   if (route === '/settings') return true;
   return maturity === 'stable' || (role === 'contributor' && (maturity === 'beta' || maturity === 'tool'));
 }
+

package/src/maturity/tui-slash-maturity.ts

@@ -0,0 +1,31 @@
+// MAT1b — TUI slash suggestions use the same maturity source as PWA routes.
+// Kept out of feature-maturity.ts: the PWA bundles that file, and this one
+// needs the TUI command list.
+import { SLASH_COMMANDS } from '../chat/index.js';
+import { getUserConfig } from '../user-config.js';
+import { FEATURE_MATURITY, type Maturity, type Role } from './feature-maturity.js';
+
+export function readTuiSlashAudience(raw: unknown = getUserConfig().raw?.tui): { role: Role; showBeta: boolean } {
+  const tui = raw && typeof raw === 'object' && !Array.isArray(raw) ? raw as Record<string, unknown> : {};
+  const role = tui.role === 'general' || tui.role === 'contributor' || tui.role === 'owner' ? tui.role : 'owner';
+  return { role, showBeta: tui.showBeta === true };
+}
+
+export function slashMaturity(name: string): Maturity | undefined {
+  const command = SLASH_COMMANDS.find((entry) => entry.name === name || entry.aliases?.includes(name));
+  if (!command) return undefined;
+  return FEATURE_MATURITY.tuiSlash[command.name as keyof typeof FEATURE_MATURITY.tuiSlash];
+}
+
+/** Visibility of a TUI slash suggestion, not permission to execute a typed command.
+ * general = stable (+ beta with showBeta) · contributor = stable·beta·tool · owner = all.
+ * Registered commands without a maturity grade remain visible to owner only in picker/help;
+ * unregistered names are never visible through this predicate. */
+export function slashVisibleFor(name: string, role: Role, { showBeta }: { showBeta: boolean }): boolean {
+  const grade = slashMaturity(name);
+  if (!grade) return false;
+  if (role === 'owner') return true;
+  if (grade === 'stable') return true;
+  if (role === 'contributor') return grade === 'beta' || grade === 'tool';
+  return grade === 'beta' && showBeta;
+}