@bradheitmann/odin-sentinel 0.2.1 → 0.4.3

package/dist/src/telemetry/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../../src/telemetry/config.ts"],"names":[],"mappings":"AAMA,MAAM,gBAAgB,GAAG,yBAAyB,CAAC;AAEnD,MAAM,UAAU,mBAAmB,CAAC,MAAyB,OAAO,CAAC,GAAG;IACtE,MAAM,GAAG,GAAG,GAAG,CAAC,gBAAgB,CAAC,CAAC;IAClC,MAAM,QAAQ,GAAG,OAAO,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IAC3D,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1B,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;IACpE,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;AACpD,CAAC;AAED,OAAO,EAAE,gBAAgB,EAAE,CAAC"}

package/dist/src/telemetry/index.d.ts

@@ -0,0 +1,7 @@
+export { readTelemetryConfig, ENDPOINT_ENV_VAR } from "./config.js";
+export type { TelemetryConfig } from "./config.js";
+export { redactString, redactPayload } from "./redactor.js";
+export { compileSessionReport } from "./report.js";
+export type { HaltEntry, ModelSignal, SessionReport, SessionReportInput, ViolationEntry } from "./report.js";
+export { submitSessionReport } from "./submit.js";
+export type { SubmitOptions, SubmitResult } from "./submit.js";

package/dist/src/telemetry/index.js

@@ -0,0 +1,5 @@
+export { readTelemetryConfig, ENDPOINT_ENV_VAR } from "./config.js";
+export { redactString, redactPayload } from "./redactor.js";
+export { compileSessionReport } from "./report.js";
+export { submitSessionReport } from "./submit.js";
+//# sourceMappingURL=index.js.map

package/dist/src/telemetry/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/telemetry/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEpE,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC5D,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAQnD,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC"}

package/dist/src/telemetry/redactor.d.ts

@@ -0,0 +1,2 @@
+export declare function redactString(value: string): string;
+export declare function redactPayload<T>(payload: T): T;

package/dist/src/telemetry/redactor.js

@@ -0,0 +1,45 @@
+// Pre-redaction for outbound payloads. Strips file-system paths, email
+// addresses, and common secret token shapes. Intentionally conservative:
+// over-redacts rather than under-redacts.
+const SLASH = "/";
+const BACKSLASH = "\\";
+const HOME_USERS_RE = new RegExp(`${SLASH}${"U" + "sers"}${SLASH}[^${SLASH}\\s"']+`, "g");
+const HOME_LINUX_RE = new RegExp(`${SLASH}${"ho" + "me"}${SLASH}[^${SLASH}\\s"']+`, "g");
+const HOME_WIN_RE = new RegExp(`${BACKSLASH}${BACKSLASH}${"U" + "sers"}${BACKSLASH}${BACKSLASH}[^${BACKSLASH}\\s"']+`, "g");
+const EMAIL_RE = /[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/g;
+// Common secret-token shapes. The set is conservative; readers should add
+// project-specific patterns if they ship custom token prefixes.
+const TOKEN_PATTERNS = [
+    /\bsk-[a-zA-Z0-9]{20,}\b/g,
+    /\blin_api_[a-zA-Z0-9]{16,}\b/g,
+    /\bghp_[a-zA-Z0-9]{20,}\b/g,
+    /\bgho_[a-zA-Z0-9]{20,}\b/g,
+    /\bAIza[0-9A-Za-z_-]{30,}\b/g,
+    /\bxox[bp]-[a-zA-Z0-9-]{20,}\b/g
+];
+export function redactString(value) {
+    let result = value
+        .replace(HOME_USERS_RE, "<HOME>")
+        .replace(HOME_LINUX_RE, "<HOME>")
+        .replace(HOME_WIN_RE, "<HOME>")
+        .replace(EMAIL_RE, "<EMAIL>");
+    for (const pattern of TOKEN_PATTERNS) {
+        result = result.replace(pattern, "<TOKEN>");
+    }
+    return result;
+}
+export function redactPayload(payload) {
+    if (typeof payload === "string")
+        return redactString(payload);
+    if (Array.isArray(payload))
+        return payload.map((entry) => redactPayload(entry));
+    if (payload && typeof payload === "object") {
+        const result = {};
+        for (const [key, value] of Object.entries(payload)) {
+            result[key] = redactPayload(value);
+        }
+        return result;
+    }
+    return payload;
+}
+//# sourceMappingURL=redactor.js.map

package/dist/src/telemetry/redactor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"redactor.js","sourceRoot":"","sources":["../../../src/telemetry/redactor.ts"],"names":[],"mappings":"AAAA,uEAAuE;AACvE,yEAAyE;AACzE,0CAA0C;AAE1C,MAAM,KAAK,GAAG,GAAG,CAAC;AAClB,MAAM,SAAS,GAAG,IAAI,CAAC;AAEvB,MAAM,aAAa,GAAG,IAAI,MAAM,CAC9B,GAAG,KAAK,GAAG,GAAG,GAAG,MAAM,GAAG,KAAK,KAAK,KAAK,SAAS,EAClD,GAAG,CACJ,CAAC;AACF,MAAM,aAAa,GAAG,IAAI,MAAM,CAC9B,GAAG,KAAK,GAAG,IAAI,GAAG,IAAI,GAAG,KAAK,KAAK,KAAK,SAAS,EACjD,GAAG,CACJ,CAAC;AACF,MAAM,WAAW,GAAG,IAAI,MAAM,CAC5B,GAAG,SAAS,GAAG,SAAS,GAAG,GAAG,GAAG,MAAM,GAAG,SAAS,GAAG,SAAS,KAAK,SAAS,SAAS,EACtF,GAAG,CACJ,CAAC;AAEF,MAAM,QAAQ,GAAG,iDAAiD,CAAC;AAEnE,0EAA0E;AAC1E,gEAAgE;AAChE,MAAM,cAAc,GAAa;IAC/B,0BAA0B;IAC1B,+BAA+B;IAC/B,2BAA2B;IAC3B,2BAA2B;IAC3B,6BAA6B;IAC7B,gCAAgC;CACjC,CAAC;AAEF,MAAM,UAAU,YAAY,CAAC,KAAa;IACxC,IAAI,MAAM,GAAG,KAAK;SACf,OAAO,CAAC,aAAa,EAAE,QAAQ,CAAC;SAChC,OAAO,CAAC,aAAa,EAAE,QAAQ,CAAC;SAChC,OAAO,CAAC,WAAW,EAAE,QAAQ,CAAC;SAC9B,OAAO,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;IAChC,KAAK,MAAM,OAAO,IAAI,cAAc,EAAE,CAAC;QACrC,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;IAC9C,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,aAAa,CAAI,OAAU;IACzC,IAAI,OAAO,OAAO,KAAK,QAAQ;QAAE,OAAO,YAAY,CAAC,OAAO,CAAiB,CAAC;IAC9E,IAAI,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC;QAAE,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,aAAa,CAAC,KAAK,CAAC,CAAiB,CAAC;IAChG,IAAI,OAAO,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;QAC3C,MAAM,MAAM,GAA4B,EAAE,CAAC;QAC3C,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAkC,CAAC,EAAE,CAAC;YAC9E,MAAM,CAAC,GAAG,CAAC,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;QACrC,CAAC;QACD,OAAO,MAAsB,CAAC;IAChC,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/src/telemetry/report.d.ts

@@ -0,0 +1,30 @@
+export type ViolationEntry = {
+    class: string;
+    description?: string;
+};
+export type HaltEntry = {
+    source: string;
+    target: string;
+    trigger: string;
+};
+export type ModelSignal = {
+    role: string;
+    model: string;
+    violations: number;
+};
+export type SessionReportInput = {
+    teamCount: number;
+    violations: ViolationEntry[];
+    halts: HaltEntry[];
+    layoutDriftEvents: number;
+    peakContextPct: number;
+    closeoutClean: boolean;
+    modelSignals: ModelSignal[];
+};
+export type SessionReport = SessionReportInput & {
+    version: string;
+    compiledAt: string;
+    violationCount: number;
+    haltCount: number;
+};
+export declare function compileSessionReport(input: SessionReportInput, version: string): SessionReport;

package/dist/src/telemetry/report.js

@@ -0,0 +1,10 @@
+export function compileSessionReport(input, version) {
+    return {
+        ...input,
+        version,
+        compiledAt: new Date().toISOString(),
+        violationCount: input.violations.length,
+        haltCount: input.halts.length
+    };
+}
+//# sourceMappingURL=report.js.map

package/dist/src/telemetry/report.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"report.js","sourceRoot":"","sources":["../../../src/telemetry/report.ts"],"names":[],"mappings":"AAkCA,MAAM,UAAU,oBAAoB,CAAC,KAAyB,EAAE,OAAe;IAC7E,OAAO;QACL,GAAG,KAAK;QACR,OAAO;QACP,UAAU,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACpC,cAAc,EAAE,KAAK,CAAC,UAAU,CAAC,MAAM;QACvC,SAAS,EAAE,KAAK,CAAC,KAAK,CAAC,MAAM;KAC9B,CAAC;AACJ,CAAC"}

package/dist/src/telemetry/submit.d.ts

@@ -0,0 +1,14 @@
+import { type TelemetryConfig } from "./config.js";
+export type SubmitResult = {
+    submitted: boolean;
+    endpoint?: string;
+    status?: number;
+    id?: string;
+    reason?: string;
+};
+export type SubmitOptions = {
+    config?: TelemetryConfig;
+    fetchImpl?: typeof fetch;
+    timeoutMs?: number;
+};
+export declare function submitSessionReport(report: Record<string, unknown>, options?: SubmitOptions): Promise<SubmitResult>;

package/dist/src/telemetry/submit.js

@@ -0,0 +1,50 @@
+import { readTelemetryConfig } from "./config.js";
+import { redactPayload } from "./redactor.js";
+const DEFAULT_TIMEOUT_MS = 8000;
+export async function submitSessionReport(report, options = {}) {
+    const config = options.config ?? readTelemetryConfig();
+    if (!config.enabled || !config.endpoint) {
+        return {
+            submitted: false,
+            reason: "telemetry not configured (set ODIN_TELEMETRY_ENDPOINT to opt in)"
+        };
+    }
+    const redacted = redactPayload(report);
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const response = await fetchImpl(config.endpoint, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify(redacted),
+            signal: controller.signal
+        });
+        let parsed = {};
+        try {
+            parsed = (await response.json());
+        }
+        catch {
+            // non-JSON response is acceptable; status code is the source of truth
+        }
+        return {
+            submitted: response.ok,
+            endpoint: config.endpoint,
+            status: response.status,
+            id: typeof parsed.id === "string" ? parsed.id : undefined,
+            reason: response.ok ? undefined : `HTTP ${response.status}`
+        };
+    }
+    catch (error) {
+        return {
+            submitted: false,
+            endpoint: config.endpoint,
+            reason: error instanceof Error ? error.message : "network error"
+        };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+//# sourceMappingURL=submit.js.map

package/dist/src/telemetry/submit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"submit.js","sourceRoot":"","sources":["../../../src/telemetry/submit.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAwB,MAAM,aAAa,CAAC;AACxE,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAgB9C,MAAM,kBAAkB,GAAG,IAAI,CAAC;AAEhC,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,MAA+B,EAC/B,UAAyB,EAAE;IAE3B,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,mBAAmB,EAAE,CAAC;IACvD,IAAI,CAAC,MAAM,CAAC,OAAO,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC;QACxC,OAAO;YACL,SAAS,EAAE,KAAK;YAChB,MAAM,EAAE,kEAAkE;SAC3E,CAAC;IACJ,CAAC;IAED,MAAM,QAAQ,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;IACvC,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,KAAK,CAAC;IAC7C,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,kBAAkB,CAAC;IAE1D,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;IACzC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,SAAS,CAAC,CAAC;IAE9D,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,MAAM,SAAS,CAAC,MAAM,CAAC,QAAQ,EAAE;YAChD,MAAM,EAAE,MAAM;YACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;YAC/C,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC;YAC9B,MAAM,EAAE,UAAU,CAAC,MAAM;SAC1B,CAAC,CAAC;QAEH,IAAI,MAAM,GAAmC,EAAE,CAAC;QAChD,IAAI,CAAC;YACH,MAAM,GAAG,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAmC,CAAC;QACrE,CAAC;QAAC,MAAM,CAAC;YACP,sEAAsE;QACxE,CAAC;QAED,OAAO;YACL,SAAS,EAAE,QAAQ,CAAC,EAAE;YACtB,QAAQ,EAAE,MAAM,CAAC,QAAQ;YACzB,MAAM,EAAE,QAAQ,CAAC,MAAM;YACvB,EAAE,EAAE,OAAO,MAAM,CAAC,EAAE,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS;YACzD,MAAM,EAAE,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,QAAQ,QAAQ,CAAC,MAAM,EAAE;SAC5D,CAAC;IACJ,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO;YACL,SAAS,EAAE,KAAK;YAChB,QAAQ,EAAE,MAAM,CAAC,QAAQ;YACzB,MAAM,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe;SACjE,CAAC;IACJ,CAAC;YAAS,CAAC;QACT,YAAY,CAAC,KAAK,CAAC,CAAC;IACtB,CAAC;AACH,CAAC"}

package/docs/reference/distribution.md

@@ -5,26 +5,34 @@ an npm package that ships prebuilt JavaScript and protocol files.
 
 ## Recommended Install Path
 
-After publishing:
-
 ```bash
-pnpm dlx odin-sentinel
+npm i -g @bradheitmann/odin-sentinel
 ```
 
-MCP client configuration can then use:
+MCP client configuration can then use the installed binary directly:
 
 ```json
 {
   "mcpServers": {
     "odin-sentinel": {
-      "command": "pnpm",
-      "args": ["dlx", "odin-sentinel"]
+      "command": "odin-sentinel-mcp"
     }
   }
 }
 ```
 
-`npx -y odin-sentinel` is also viable for npm-first clients.
+For zero-install via `npx`:
+
+```json
+{
+  "mcpServers": {
+    "odin-sentinel": {
+      "command": "npx",
+      "args": ["-y", "-p", "@bradheitmann/odin-sentinel", "odin-sentinel-mcp"]
+    }
+  }
+}
+```
 
 ## Local Clone Path
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bradheitmann/odin-sentinel",
-  "version": "0.2.1",
+  "version": "0.4.3",
   "publishConfig": {
     "access": "public"
   },

package/protocol/SCP.md

@@ -1,13 +1,14 @@
 # ODIN Sentinel Coordination Protocol
 
-Version: 0.2.1
+Version: 0.3.0
 
 ODIN Sentinel is a portable coordination layer for visible multi-agent teams.
 SCP means Sentinel Coordination Protocol in this repository. It is not Secure
 Copy.
 It provides generic role contracts, startup packets, receipt validation, team
 manifest validation, native visible-role delegation packets, closeout
-checklists, and fallback protocol snapshots through an MCP server.
+checklists, surface layout rules, and fallback protocol snapshots through an
+MCP server.
 
 ## Principles
 
@@ -19,12 +20,23 @@ checklists, and fallback protocol snapshots through an MCP server.
 - Handoffs, closeout, and restart packets must be explicit.
 - Secrets are never printed or embedded in receipts.
 - Delegation is native to the server and must not require an external extension.
+- Staffing and surface custodianship are the sole authority of A/EXEC-PM.
 
 ## Startup Defaults
 
 Fresh startup creates an executive office and one development pod unless the
 user or a handoff requests another topology.
 
+## Surface Layout
+
+CMUX surface organization is contractually fixed by `surface_layout` in
+`topology.yaml` and the `odin.compute_surface_layout` tool. All columns are
+equal width. At most two surfaces stack inside any column. Team A always
+occupies column 0; when the team count is odd and at least 3, column 0 holds
+only Team A (the tall column). EXEC PM must call
+`odin.compute_surface_layout` (and its gate variant) before any spawn beyond
+A/EXEC and must reach the target layout via CMUX splits before dispatching.
+
 ## Closeout Defaults
 
 Closeout supports two modes:
@@ -32,3 +44,37 @@ Closeout supports two modes:
 - `PARK_FOR_CONTINUITY`: keep role slots open and park occupants.
 - `FULL_SESSION_SHUTDOWN`: quit occupants, verify exit, and close panes except
   the final user-designated surface.
+
+## Meta-Governance
+
+ODIN Sentinel applies the same Dev/QA contract that governs code execution to
+the execution of organizational strategy itself.
+
+In code work:
+
+- DEV implements bounded scope and produces evidence.
+- QA verifies independently and does not accept their own work.
+- TEAM PM routes tasks to workers; A/EXEC-PM authorizes and frames claims.
+
+In organizational work:
+
+- TEAM PM is the Dev of org strategy. It implements the staffing, surfaces,
+  and delegations issued by A/EXEC-PM (subject to the constraint that TEAM PM
+  cannot self-staff).
+- A/EXEC-PM is the dispatcher of org strategy. It issues the org orders and
+  owns staffing and surface custodianship exclusively.
+- ODIN agents are the QA of org strategy. They audit whether A/EXEC-PM's org
+  orders are executed correctly, whether surface custodianship is honored,
+  whether protocol adherence holds, whether context windows are healthy, and
+  whether contracts remain accountable.
+
+ODIN agents hold intervention authority. When A/EXEC-PM, any TEAM PM, or any
+worker violates the contract (staffing without the surface gate, hidden agent
+creation, same-role QA acceptance, context window over hard threshold without
+compaction), the supervising ODIN role MAY issue a HALT directive. The
+receiving role is contractually obligated to honor the HALT and reply with a
+remediation plan before resuming. Continuing past a HALT without remediation
+is itself a protocol breach.
+
+This recursion is why the same protocol governs both code work and
+organizational work without growing new vocabulary.