comisai 1.0.34 → 1.0.36

package/node_modules/@comis/scheduler/dist/index.js

@@ -7,6 +7,8 @@ export { createCronStore } from "./cron/index.js";
 export { createCronScheduler } from "./cron/index.js";
 // Execution safety
 export { createExecutionTracker } from "./execution/index.js";
+// File-based execution lock (consumed by @comis/agent OAuth file adapter + token manager)
+export { withExecutionLock, isLocked } from "./execution/execution-lock.js";
 // Heartbeat monitoring
 export { HEARTBEAT_OK_TOKEN, createHeartbeatRunner } from "./heartbeat/index.js";
 // Per-agent heartbeat config resolution

package/node_modules/@comis/scheduler/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@comis/scheduler",
   "private": true,
-  "version": "1.0.34",
+  "version": "1.0.36",
   "author": "Moshe Anconina",
   "license": "Apache-2.0",
   "description": "Task scheduling and cron management for Comis",

package/node_modules/@comis/shared/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@comis/shared",
   "private": true,
-  "version": "1.0.34",
+  "version": "1.0.36",
   "author": "Moshe Anconina",
   "license": "Apache-2.0",
   "description": "Shared types and utilities for the Comis platform",

package/node_modules/@comis/skills/dist/bridge/schema-validator.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Generic tool-entry schema validator.
+ *
+ * Pre-flight, action-aware shape gate that runs BEFORE per-tool
+ * `validateInput`. Catches malformed shapes such as
+ * `mcp_manage({action:"connect", server_name:"yfinance"})` at the
+ * tool-entry boundary and produces a self-correcting message:
+ *
+ *     "[invalid_value] unknown key 'server_name' -- did you mean 'name'?.
+ *      missing for action='connect': transport.
+ *      valid keys: action, name, transport, command, args, url, headers"
+ *
+ * Generic by construction: every per-tool branch lives in the metadata
+ * registered via `registerToolMetadata({ validActions, validKeys,
+ *   requiredByAction })`. This file contains zero tool-name conditionals.
+ *
+ * Reuses `levenshteinSimilarity` from
+ * ../builtin/file/path-suggest.js -- DO NOT duplicate the helper.
+ *
+ * Returns a single error string on failure (matches the
+ * `validateInput` contract used by `wrapWithMetadataEnforcement`),
+ * `undefined` on success. Caller prepends `[invalid_value]`.
+ *
+ * @module
+ */
+import type { ComisToolMetadata } from "@comis/core";
+/**
+ * Validate tool-entry shape against registered metadata.
+ *
+ * @param params - Raw params object as the SDK would pass to `execute()`.
+ * @param meta - Metadata returned from `getToolMetadata(toolName)`. May be
+ *   undefined or missing the entry-shape fields -- in either case this
+ *   function returns undefined (no-op) so existing tools without
+ *   registered shape metadata pass through unchanged.
+ * @returns A single error string when validation fails (caller prepends
+ *   `[invalid_value]`), or `undefined` when validation passes / is skipped.
+ */
+export declare function validateToolEntry(params: unknown, meta: ComisToolMetadata | undefined): string | undefined;

package/node_modules/@comis/skills/dist/bridge/schema-validator.js

@@ -0,0 +1,169 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Generic tool-entry schema validator.
+ *
+ * Pre-flight, action-aware shape gate that runs BEFORE per-tool
+ * `validateInput`. Catches malformed shapes such as
+ * `mcp_manage({action:"connect", server_name:"yfinance"})` at the
+ * tool-entry boundary and produces a self-correcting message:
+ *
+ *     "[invalid_value] unknown key 'server_name' -- did you mean 'name'?.
+ *      missing for action='connect': transport.
+ *      valid keys: action, name, transport, command, args, url, headers"
+ *
+ * Generic by construction: every per-tool branch lives in the metadata
+ * registered via `registerToolMetadata({ validActions, validKeys,
+ *   requiredByAction })`. This file contains zero tool-name conditionals.
+ *
+ * Reuses `levenshteinSimilarity` from
+ * ../builtin/file/path-suggest.js -- DO NOT duplicate the helper.
+ *
+ * Returns a single error string on failure (matches the
+ * `validateInput` contract used by `wrapWithMetadataEnforcement`),
+ * `undefined` on success. Caller prepends `[invalid_value]`.
+ *
+ * @module
+ */
+import { levenshteinSimilarity } from "../builtin/file/path-suggest.js";
+/**
+ * Min similarity for did-you-mean suggestion. Below this we say "unknown"
+ * with no suggestion to avoid misleading the LLM.
+ *
+ * We score with `tokenAwareSimilarity` (max of full-string similarity and
+ * the best per-token similarity after splitting on `_`/`-`). This catches
+ * payloads like `server_name -> name` (token "name" matches exactly,
+ * score 1.0) without spurious matches against short unrelated keys (`x`,
+ * `srver` -> max < 0.3 across all candidates in the 7-key mcp_manage
+ * shape, well below threshold).
+ *
+ * 0.5 was chosen empirically: `conect -> connect` scores 0.857 (fires);
+ * `srver -> headers` scores 0.286 (does not fire); the closest false
+ * positive across the manage-tool corpus is below 0.5.
+ */
+const SUGGEST_THRESHOLD = 0.5;
+/**
+ * Validate tool-entry shape against registered metadata.
+ *
+ * @param params - Raw params object as the SDK would pass to `execute()`.
+ * @param meta - Metadata returned from `getToolMetadata(toolName)`. May be
+ *   undefined or missing the entry-shape fields -- in either case this
+ *   function returns undefined (no-op) so existing tools without
+ *   registered shape metadata pass through unchanged.
+ * @returns A single error string when validation fails (caller prepends
+ *   `[invalid_value]`), or `undefined` when validation passes / is skipped.
+ */
+export function validateToolEntry(params, meta) {
+    // Skip if no entry-shape metadata registered.
+    if (meta === undefined
+        || (meta.validActions === undefined
+            && meta.validKeys === undefined
+            && meta.requiredByAction === undefined)) {
+        return undefined;
+    }
+    // Shape gate: params MUST be a plain object. Reject null, primitives,
+    // and arrays. (Arrays would otherwise pass typeof === "object".)
+    if (params === null || typeof params !== "object" || Array.isArray(params)) {
+        return "params must be an object";
+    }
+    const p = params;
+    const segments = [];
+    // Action gate.
+    let action;
+    if (meta.validActions !== undefined) {
+        const raw = p.action;
+        if (raw === undefined) {
+            segments.push(`Missing required parameter: action. valid actions: ${meta.validActions.join(", ")}`);
+        }
+        else if (typeof raw !== "string") {
+            segments.push("action must be a string");
+        }
+        else if (!meta.validActions.includes(raw)) {
+            const suggestion = bestMatch(raw, meta.validActions);
+            const didYouMean = suggestion !== undefined ? ` -- did you mean '${suggestion}'?` : "";
+            segments.push(`invalid action '${raw}'${didYouMean}. valid actions: ${meta.validActions.join(", ")}`);
+        }
+        else {
+            action = raw;
+        }
+    }
+    else if (typeof p.action === "string") {
+        // No validActions registered but the tool still uses an action field
+        // (rare). Use it for requiredByAction lookup.
+        action = p.action;
+    }
+    // Unknown-key gate.
+    if (meta.validKeys !== undefined) {
+        const validSet = new Set(meta.validKeys);
+        const unknowns = [];
+        for (const key of Object.keys(p)) {
+            if (!validSet.has(key))
+                unknowns.push(key);
+        }
+        if (unknowns.length > 0) {
+            const parts = unknowns.map((k) => {
+                const suggestion = bestMatch(k, meta.validKeys);
+                return suggestion !== undefined
+                    ? `unknown key '${k}' -- did you mean '${suggestion}'?`
+                    : `unknown key '${k}'`;
+            });
+            segments.push(parts.join("; "));
+        }
+    }
+    // Required-fields gate (only when we have a known action).
+    if (action !== undefined && meta.requiredByAction !== undefined) {
+        const required = meta.requiredByAction[action];
+        if (required !== undefined && required.length > 0) {
+            const missing = required.filter((k) => !(k in p) || p[k] === undefined);
+            if (missing.length > 0) {
+                segments.push(`missing for action='${action}': ${missing.join(", ")}`);
+            }
+        }
+    }
+    if (segments.length === 0)
+        return undefined;
+    // Always append valid-keys list when registered -- closes the LLM's
+    // self-correction loop in one turn.
+    if (meta.validKeys !== undefined) {
+        segments.push(`valid keys: ${meta.validKeys.join(", ")}`);
+    }
+    return segments.join(". ");
+}
+/** Pick the best-matching candidate above SUGGEST_THRESHOLD, or undefined. */
+function bestMatch(input, candidates) {
+    let best;
+    const lowered = input.toLowerCase();
+    for (const candidate of candidates) {
+        const score = tokenAwareSimilarity(lowered, candidate.toLowerCase());
+        if (score >= SUGGEST_THRESHOLD && (best === undefined || score > best.score)) {
+            best = { value: candidate, score };
+        }
+    }
+    return best?.value;
+}
+/**
+ * Token-aware similarity: max of full-string similarity and the best
+ * per-token similarity after splitting `input` on `_`/`-`.
+ *
+ * Plain Levenshtein on full strings misses snake_case key suggestions:
+ * `server_name` vs `name` is similarity 0.36, well below any reasonable
+ * threshold. Splitting on `_` exposes the `name` token (similarity 1.0
+ * vs `name`), which is the LLM-self-correction signal we want to surface.
+ *
+ * Inputs are assumed lowercased by the caller.
+ */
+function tokenAwareSimilarity(input, candidate) {
+    let best = levenshteinSimilarity(input, candidate);
+    // Split on '_' or '-' (skill, manage-tool, snake_case conventions). Empty
+    // tokens are dropped so leading/trailing/double-separators do not produce
+    // 0-length strings that would skew similarity to 1.0 against an empty
+    // candidate (defensive -- candidate is non-empty in practice).
+    const tokens = input.split(/[_-]+/);
+    for (const t of tokens) {
+        if (t.length === 0)
+            continue;
+        const score = levenshteinSimilarity(t, candidate);
+        if (score > best)
+            best = score;
+    }
+    return best;
+}

package/node_modules/@comis/skills/dist/bridge/tool-metadata-enforcement.js

@@ -11,6 +11,7 @@
  * @module
  */
 import { getToolMetadata, truncateContentBlocks } from "@comis/core";
+import { validateToolEntry } from "./schema-validator.js";
 /**
  * Check whether a tool result's content is effectively empty.
  *
@@ -60,6 +61,17 @@ export function wrapWithMetadataEnforcement(tool) {
         ...tool,
         async execute(toolCallId, params, signal, onUpdate) {
             const meta = getToolMetadata(tool.name);
+            // Generic tool-entry schema validation (260504-cac).
+            // Runs BEFORE per-tool validateInput so action-shape errors short-circuit
+            // before tool-specific business rules. Skips silently when the tool has
+            // not registered validActions / validKeys / requiredByAction.
+            const schemaError = validateToolEntry(params, meta);
+            if (schemaError !== undefined) {
+                const err = new Error(`[invalid_value] ${schemaError}`);
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any -- match existing errorKind propagation pattern
+                err.errorKind = "validation";
+                throw err;
+            }
             // Pre-flight validation
             if (meta?.validateInput) {
                 const validationError = await meta.validateInput(params);

package/node_modules/@comis/skills/dist/bridge/tool-metadata-registry.js

@@ -188,6 +188,136 @@ export function registerAllToolMetadata() {
         },
     });
     // =========================================================================
+    // Tool-Entry Schema (260504-cac)
+    //
+    // Generic action enum + valid keys + per-action required fields. Consumed
+    // by validateToolEntry() in ./schema-validator.ts via
+    // wrapWithMetadataEnforcement BEFORE per-tool validateInput runs.
+    //
+    // Each tool's shape is sourced from its TypeBox Type.Union([Type.Literal(...)])
+    // action enum + each action handler's readStringParam(p, X) /
+    // throwToolError("missing_param", ...) calls in its actionOverrides.
+    //
+    // Cross-consistency: managed-section entries in
+    // @comis/core/src/config/managed-sections.ts also declare
+    // requiredByAction for the redirect-hint payload. The registrations
+    // here are the runtime gate; the managed-section entries are the
+    // user-facing redirect hint.
+    // =========================================================================
+    registerToolMetadata("mcp_manage", {
+        validActions: ["list", "status", "connect", "disconnect", "reconnect"],
+        validKeys: ["action", "server_name", "transport", "command", "args", "url", "headers"],
+        // connect requires [server_name, transport]; command (stdio) / url (sse|http) are
+        // transport-conditional and validated downstream by the handler.
+        requiredByAction: {
+            status: ["server_name"],
+            connect: ["server_name", "transport"],
+            disconnect: ["server_name"],
+            reconnect: ["server_name"],
+        },
+    });
+    registerToolMetadata("agents_manage", {
+        validActions: ["create", "get", "update", "delete", "suspend", "resume", "list"],
+        validKeys: ["action", "agent_id", "config"],
+        // agent_id is required for every action except list.
+        requiredByAction: {
+            create: ["agent_id", "config"],
+            get: ["agent_id"],
+            update: ["agent_id", "config"],
+            delete: ["agent_id"],
+            suspend: ["agent_id"],
+            resume: ["agent_id"],
+        },
+    });
+    registerToolMetadata("tokens_manage", {
+        validActions: ["list", "create", "revoke", "rotate"],
+        validKeys: ["action", "token_id", "scopes"],
+        // create: token_id is auto-generated when omitted (per the schema +
+        // handler's non-required readStringParam call); only scopes is strictly
+        // required.
+        requiredByAction: {
+            create: ["scopes"],
+            revoke: ["token_id"],
+            rotate: ["token_id"],
+        },
+    });
+    registerToolMetadata("providers_manage", {
+        validActions: ["list", "get", "create", "update", "delete", "enable", "disable"],
+        validKeys: ["action", "provider_id", "config"],
+        requiredByAction: {
+            get: ["provider_id"],
+            create: ["provider_id", "config"],
+            update: ["provider_id", "config"],
+            delete: ["provider_id"],
+            enable: ["provider_id"],
+            disable: ["provider_id"],
+        },
+    });
+    registerToolMetadata("channels_manage", {
+        validActions: ["list", "get", "enable", "disable", "restart", "configure"],
+        validKeys: ["action", "channel_type", "setting", "enabled"],
+        requiredByAction: {
+            get: ["channel_type"],
+            enable: ["channel_type"],
+            disable: ["channel_type"],
+            restart: ["channel_type"],
+            configure: ["channel_type", "setting", "enabled"],
+        },
+    });
+    registerToolMetadata("sessions_manage", {
+        validActions: ["delete", "reset", "export", "compact"],
+        validKeys: ["action", "session_key", "instructions"],
+        requiredByAction: {
+            delete: ["session_key"],
+            reset: ["session_key"],
+            export: ["session_key"],
+            compact: ["session_key"],
+        },
+    });
+    registerToolMetadata("skills_manage", {
+        validActions: ["list", "import", "delete", "create", "update"],
+        validKeys: ["action", "url", "name", "content", "description", "scope"],
+        requiredByAction: {
+            import: ["url"],
+            delete: ["name"],
+            create: ["name", "content"],
+            update: ["name", "content"],
+        },
+    });
+    registerToolMetadata("memory_manage", {
+        validActions: ["stats", "browse", "delete", "flush", "export"],
+        validKeys: [
+            "action", "tenant_id", "agent_id", "ids", "offset", "limit", "sort",
+            "memory_type", "trust_level", "tags",
+        ],
+        // tenant_id / agent_id are scope filters with defaults; only ids is
+        // strictly required (for delete).
+        requiredByAction: {
+            delete: ["ids"],
+        },
+    });
+    registerToolMetadata("models_manage", {
+        validActions: ["list", "test", "list_providers"],
+        validKeys: ["action", "provider", "model"],
+        requiredByAction: {
+            test: ["provider", "model"],
+        },
+    });
+    registerToolMetadata("heartbeat_manage", {
+        validActions: ["get", "update", "status", "trigger"],
+        validKeys: [
+            "action", "agent_id", "enabled", "interval_ms", "prompt", "model",
+            "target_channel_type", "target_channel_id", "target_chat_id", "target_is_dm",
+            "light_context", "show_ok", "show_alerts", "allow_dm",
+            "skip_heartbeat_only_delivery", "ack_max_chars", "response_prefix", "session",
+            "alert_threshold", "alert_cooldown_ms", "stale_ms",
+        ],
+        // Every action's params beyond `action` are Type.Optional. Empty
+        // requiredByAction still gates unknown action values + unknown keys via
+        // validActions / validKeys.
+        requiredByAction: {},
+    });
+    // =========================================================================
     // Output Schemas
     // =========================================================================
     registerToolMetadata("read", {

package/node_modules/@comis/skills/dist/builtin/exec-diagnostics.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Exec failure diagnostics: pattern-based recovery hints for known-recoverable
+ * subprocess failures. Pure functions — no throws, no I/O beyond synchronous
+ * filesystem existence checks scoped to `cwd` via safePath.
+ *
+ * Wired into executeForeground's stderr finalization in exec-tool.ts. When a
+ * matcher returns non-null, its hint is prepended to finalStderr with a
+ * `RECOVERY HINT:` prefix so the LLM sees actionable recovery info at the head
+ * of the error stream — same surfacing pattern as the existing
+ * breakSystemWarning on stdout.
+ *
+ * Day 1 ships ONE matcher (Python ModuleNotFoundError + missing pyproject.toml).
+ * Future matchers register as additional entries in the matchers array — no
+ * edits to exec-tool.ts required.
+ *
+ * @module
+ */
+export interface ExecRecoveryInput {
+    /** Final stderr text (post-truncation, post-timeout/abort suffix). */
+    stderr: string;
+    /** Process exit code. Matchers may early-return on 0. */
+    exitCode: number;
+    /** Absolute working directory the command ran in. Already workspace-bounded by exec-tool's resolveCwd. */
+    cwd: string;
+}
+/**
+ * Run all registered matchers against the failed exec result. Returns the
+ * first non-null hint, or `null` if no matcher applies. Multiple-hint
+ * concatenation is intentionally not supported on Day 1 — keep the surface
+ * narrow until we have a second matcher to motivate the shape.
+ */
+export declare function matchExecRecoveryHint(input: ExecRecoveryInput): string | null;

package/node_modules/@comis/skills/dist/builtin/exec-diagnostics.js

@@ -0,0 +1,127 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Exec failure diagnostics: pattern-based recovery hints for known-recoverable
+ * subprocess failures. Pure functions — no throws, no I/O beyond synchronous
+ * filesystem existence checks scoped to `cwd` via safePath.
+ *
+ * Wired into executeForeground's stderr finalization in exec-tool.ts. When a
+ * matcher returns non-null, its hint is prepended to finalStderr with a
+ * `RECOVERY HINT:` prefix so the LLM sees actionable recovery info at the head
+ * of the error stream — same surfacing pattern as the existing
+ * breakSystemWarning on stdout.
+ *
+ * Day 1 ships ONE matcher (Python ModuleNotFoundError + missing pyproject.toml).
+ * Future matchers register as additional entries in the matchers array — no
+ * edits to exec-tool.ts required.
+ *
+ * @module
+ */
+import { existsSync, statSync } from "node:fs";
+import { safePath } from "@comis/core";
+// ---------------------------------------------------------------------------
+// Matcher: Python ModuleNotFoundError + missing pyproject.toml
+// ---------------------------------------------------------------------------
+/**
+ * Match `python -m foo` failures where stderr is one of:
+ *   1. `ModuleNotFoundError: No module named 'foo'`  (Python traceback form,
+ *      raised when the import fires inside Python code — e.g. `python -m a.b`
+ *      where `a` imports a missing dep, or `python -m a.b.c` where `a` itself
+ *      can't be found and Python re-raises through runpy).
+ *   2. `<python-binary>: No module named foo`        (runpy CLI form, no quotes,
+ *      end-of-line — what `python3 -m <pkg>` emits when `<pkg>` is not findable
+ *      in sys.path. This is the most common real-world trigger.)
+ *
+ * Combined with `cwd/foo/` or `cwd/src/foo/` existing AND `cwd/pyproject.toml`
+ * missing, this means the user has a Python project but no installable package
+ * metadata. Suggest writing pyproject.toml + `pip install -e .`.
+ */
+// First alternation captures from the quoted ModuleNotFoundError form;
+// second alternation captures from the bare `: No module named foo` runpy form.
+// Anchored to end-of-line (m flag) so we don't accidentally swallow trailing
+// content on the runpy form.
+const PY_MODULE_NOT_FOUND_RE = /(?:ModuleNotFoundError:\s*No module named ['"]([^'"]+)['"]|: No module named ([A-Za-z_][A-Za-z0-9_.]*)\s*$)/m;
+const SAFE_PKG_NAME_RE = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+function isDirectorySafe(p) {
+    try {
+        if (!existsSync(p))
+            return false;
+        return statSync(p).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+const matchPythonModuleNotFound = ({ stderr, exitCode, cwd }) => {
+    if (exitCode === 0)
+        return null;
+    const m = PY_MODULE_NOT_FOUND_RE.exec(stderr);
+    if (!m)
+        return null;
+    // Group 1 = quoted ModuleNotFoundError form; Group 2 = bare runpy form.
+    // For `python -m a.b.c` ModuleNotFoundError reports the LEADING segment
+    // ('a') when 'a' itself can't be found. Take the first dotted segment;
+    // anything else (hyphens, empty, leading digit) abstains via SAFE_PKG_NAME_RE.
+    const fullName = m[1] ?? m[2];
+    if (!fullName)
+        return null;
+    const pkg = fullName.split(".")[0];
+    if (!SAFE_PKG_NAME_RE.test(pkg))
+        return null;
+    try {
+        // Already-installable project — different bug, abstain.
+        const pyproject = safePath(cwd, "pyproject.toml");
+        if (existsSync(pyproject))
+            return null;
+        // Look for cwd/<pkg>/ or cwd/src/<pkg>/. Both must be directories.
+        const directDir = safePath(cwd, pkg);
+        let foundLayout = null;
+        if (isDirectorySafe(directDir)) {
+            foundLayout = "flat";
+        }
+        else {
+            const srcDir = safePath(cwd, "src");
+            if (isDirectorySafe(srcDir)) {
+                const srcPkgDir = safePath(srcDir, pkg);
+                if (isDirectorySafe(srcPkgDir)) {
+                    foundLayout = "src";
+                }
+            }
+        }
+        if (!foundLayout)
+            return null;
+        const pkgPathHint = foundLayout === "src" ? `src/${pkg}/` : `${pkg}/`;
+        const layoutTable = foundLayout === "src"
+            ? `[tool.setuptools.packages.find] where=["src"]`
+            : `[tool.setuptools] packages=["${pkg}"]`;
+        return (`RECOVERY HINT: This Python project is missing pyproject.toml. ` +
+            `Found ${pkgPathHint} but no installable package metadata, so \`python -m ${pkg}\` cannot resolve it. ` +
+            `Fix: write a minimal pyproject.toml at the project root, then \`pip install -e .\`. ` +
+            `Example: [build-system] requires=["setuptools>=61"]  [project] name="${pkg}" version="0.1.0"  ` +
+            layoutTable);
+    }
+    catch {
+        // safePath/statSync surprise — abstain rather than break exec.
+        return null;
+    }
+};
+// ---------------------------------------------------------------------------
+// Registry + entry point
+// ---------------------------------------------------------------------------
+const matchers = [
+    matchPythonModuleNotFound,
+    // Future: matchNodeModuleNotFound, matchCommandNotFound, matchEnvVarMissing, ...
+];
+/**
+ * Run all registered matchers against the failed exec result. Returns the
+ * first non-null hint, or `null` if no matcher applies. Multiple-hint
+ * concatenation is intentionally not supported on Day 1 — keep the surface
+ * narrow until we have a second matcher to motivate the shape.
+ */
+export function matchExecRecoveryHint(input) {
+    for (const m of matchers) {
+        const hit = m(input);
+        if (hit)
+            return hit;
+    }
+    return null;
+}

package/node_modules/@comis/skills/dist/builtin/exec-security.js

@@ -263,6 +263,12 @@ export const DANGEROUS_COMMAND_PATTERNS = [
             "to see which secret names are configured (names only, no values). " +
             "Secret values are never returned to the agent.",
     },
+    {
+        pattern: /\.comis\/auth-profiles\.json/,
+        reason: "Access to the OAuth credential store (auth-profiles.json) is blocked. " +
+            "It contains refresh and access tokens for every connected provider. " +
+            "Use the gateway tool to manage OAuth profiles -- token values are never returned to the agent.",
+    },
     // Category E -- Config file modification bypass
     // Defense-in-depth: the agent system prompt is the primary guard.
     // These regexes can be bypassed via quoting, variable expansion, etc.
@@ -334,6 +340,38 @@ export const DANGEROUS_COMMAND_PATTERNS = [
         pattern: /\.comis\/\.env.*(?:sed|awk|tee|cat\s*>|echo\s*>)/,
         reason: "Direct .env file modification bypasses SecretManager and audit. Credentials must be managed through secure channels.",
     },
+    {
+        pattern: /(?:sed|awk|tee|cp|mv|perl|ruby)\b.*\.comis\/auth-profiles\.json/,
+        reason: "Direct OAuth credential store (auth-profiles.json) modification bypasses atomic-write, per-profile-lock, and schema-version validation in oauth-credential-store-file.ts. Use the gateway tool to manage OAuth profiles.",
+    },
+    {
+        pattern: /(?:echo|cat)\b.*>.*\.comis\/auth-profiles\.json/,
+        reason: "Direct OAuth credential store (auth-profiles.json) modification bypasses atomic-write, per-profile-lock, and schema-version validation in oauth-credential-store-file.ts. Use the gateway tool to manage OAuth profiles.",
+    },
+    {
+        pattern: /\.comis\/auth-profiles\.json.*(?:sed|awk|tee|cat\s*>|echo\s*>)/,
+        reason: "Direct OAuth credential store (auth-profiles.json) modification bypasses atomic-write, per-profile-lock, and schema-version validation in oauth-credential-store-file.ts. Use the gateway tool to manage OAuth profiles.",
+    },
+    // Category L -- Network reverse-shell primitives
+    // Direct attack primitives that establish a remote shell without going
+    // through a pipe (so the existing Gate 2 "pipe to bash/sh/curl/wget/nc"
+    // wouldn't catch them). Defense-in-depth: the agent has no legitimate
+    // reason to use any of these — the surrounding skills wrap network access
+    // through the daemon's HTTP client. A network egress allowlist (iptables
+    // --uid-owner) is the actual security boundary; these patterns just
+    // surface intent earlier in the chain.
+    {
+        pattern: /\/dev\/tcp\//,
+        reason: "Bash /dev/tcp/<host>/<port> opens a raw TCP socket — reverse-shell primitive.",
+    },
+    {
+        pattern: /\bnc(?:at)?\b[^|;&]*\s-e\b/,
+        reason: "netcat -e (--exec) attaches a process to the socket — reverse-shell primitive.",
+    },
+    {
+        pattern: /\bsocat\b[^|;&]*\bexec\s*:/,
+        reason: "socat exec: target attaches a process to the socket — reverse-shell primitive.",
+    },
 ];
 // --------------------------------------------------------------------------
 // Dangerous path protection constants

package/node_modules/@comis/skills/dist/builtin/exec-tool.js

@@ -33,6 +33,7 @@ import { generateSessionId, appendOutput } from "./process-registry.js";
 import { truncateTail, formatSize, DEFAULT_MAX_BYTES } from "./truncate.js";
 import { createOutputCleaner } from "./output-cleaner.js";
 import { extractHeredoc, validateExecCommand, interpretExitCode } from "./exec-security.js";
+import { matchExecRecoveryHint } from "./exec-diagnostics.js";
 import { tryGetContext } from "@comis/core";
 // ---------------------------------------------------------------------------
 // Constants
@@ -722,6 +723,14 @@ function executeForeground(command, cwd, env, timeoutMs, input, signal, onUpdate
             if (aborted) {
                 finalStderr += (finalStderr ? "\n" : "") + "Process aborted by signal";
             }
+            // Recovery diagnostics: prepend a `RECOVERY HINT:` line for known-recoverable
+            // failures (e.g. Python ModuleNotFoundError + missing pyproject.toml). Same
+            // surfacing pattern as breakSystemWarning on stdout — gives the LLM an
+            // actionable next step at the HEAD of stderr instead of buried in JSON.
+            const recoveryHint = matchExecRecoveryHint({ stderr: finalStderr, exitCode, cwd });
+            if (recoveryHint) {
+                finalStderr = recoveryHint + (finalStderr ? "\n" + finalStderr : "");
+            }
             const durationMs = Math.round(performance.now() - startTime);
             logger?.debug({ toolName: "exec", durationMs, exitCode, ...(description && { description }) }, "Exec command complete");
             const result = {