aicodeman 1.33.2 → 1.34.0

package/dist/webhook-notify.d.ts

@@ -0,0 +1,71 @@
+/**
+ * @fileoverview Webhook notifications (ntfy, Slack, Discord, generic JSON) for the events that
+ * already trigger Web Push, so a headless server can reach a phone without a browser tab or a
+ * push subscription.
+ *
+ * Split in three, so the parts that matter are testable without a network:
+ *   - pure: `webhookUrlProblem`, `maskWebhookUrl`, `shouldSendWebhook`, `buildWebhookRequest`
+ *   - store: `~/.codeman/webhook.json`, written 0600 via tmp+rename (the URL is a bearer secret:
+ *     anyone holding a Slack/Discord webhook URL can post as it)
+ *   - IO: `sendWebhook` (injected fetch) and `WebhookNotifier` (dedupe, in-flight cap, last result)
+ *
+ * Rules the code keeps and the tests pin:
+ *   - The URL is configured only through the admin-only `/api/webhook` routes and kept OUT of
+ *     `settings.json`, which every logged-in user can read through `GET /api/settings`.
+ *   - Delivery goes through `webviewFetch`: link-local and cloud-metadata targets are refused on
+ *     the RESOLVED address at connect time, redirects are not followed, and the call is bounded
+ *     by a timeout. Loopback and LAN stay allowed on purpose (a local ntfy is the feature).
+ *   - The URL never appears in a log line, a result, or an error message.
+ *   - Session names and error text are user/agent-controlled, so they cannot ping a channel:
+ *     Discord gets `allowed_mentions: { parse: [] }` and Slack control characters are escaped.
+ *
+ * @module webhook-notify
+ */
+import { type WebhookConfig, type WebhookKind, type WebhookResult, type WebhookUrgency } from './types/push.js';
+export declare const DEFAULT_WEBHOOK_CONFIG: WebhookConfig;
+export interface WebhookMessage {
+    event: string;
+    title: string;
+    body: string;
+    urgency: WebhookUrgency;
+    sessionId?: string;
+    sessionName?: string;
+    /** The Codeman instance's window title, so several machines are told apart. */
+    host?: string;
+}
+/** Why `raw` cannot be a webhook URL, or null. Used at save time; delivery re-checks the resolved address. */
+export declare function webhookUrlProblem(raw: string): string | null;
+/** Scheme + host only: the path and query of a webhook URL are the secret. */
+export declare function maskWebhookUrl(raw: string): string;
+export declare function shouldSendWebhook(cfg: WebhookConfig, urgency: WebhookUrgency): boolean;
+export interface WebhookRequest {
+    method: 'POST';
+    headers: Record<string, string>;
+    body: string;
+}
+export declare function buildWebhookRequest(kind: WebhookKind, msg: WebhookMessage, now?: Date): WebhookRequest;
+export declare function webhookConfigPath(configDir: string): string;
+export declare function readWebhookConfig(configDir: string): Promise<WebhookConfig>;
+/** 0600 via tmp+rename: `mode` on writeFile only applies to a file being created. */
+export declare function writeWebhookConfig(configDir: string, cfg: WebhookConfig): Promise<void>;
+export type WebhookFetch = (target: URL, init: RequestInit) => Promise<Response>;
+export declare function sendWebhook(cfg: Pick<WebhookConfig, 'kind' | 'url'>, msg: WebhookMessage, fetchImpl: WebhookFetch): Promise<WebhookResult>;
+/**
+ * Sends the notifications the server decides on. Fire-and-forget by design (a slow webhook must
+ * never delay Web Push or a request), so it dedupes, caps what is in flight, and remembers only
+ * the last result for the Settings status line.
+ */
+export declare class WebhookNotifier {
+    private readonly load;
+    private readonly fetchImpl;
+    private readonly now;
+    private lastSent;
+    private inFlight;
+    private last;
+    constructor(load: () => Promise<WebhookConfig>, fetchImpl: WebhookFetch, now?: () => number);
+    get lastResult(): WebhookResult | null;
+    notify(msg: WebhookMessage): Promise<void>;
+    /** A deliberate test send: bypasses `enabled`, scope and dedupe, and records the result. */
+    sendTest(cfg: Pick<WebhookConfig, 'kind' | 'url'>, host?: string): Promise<WebhookResult>;
+}
+//# sourceMappingURL=webhook-notify.d.ts.map

package/dist/webhook-notify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook-notify.d.ts","sourceRoot":"","sources":["../src/webhook-notify.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAOH,OAAO,EAGL,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,aAAa,EAElB,KAAK,cAAc,EACpB,MAAM,iBAAiB,CAAC;AAUzB,eAAO,MAAM,sBAAsB,EAAE,aAA6E,CAAC;AAEnH,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,cAAc,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,+EAA+E;IAC/E,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAMD,8GAA8G;AAC9G,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAa5D;AAED,8EAA8E;AAC9E,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAOlD;AAED,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,aAAa,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAGtF;AAoBD,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,IAAI,EAAE,MAAM,CAAC;CACd;AAED,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,WAAW,EAAE,GAAG,EAAE,cAAc,EAAE,GAAG,GAAE,IAAiB,GAAG,cAAc,CAgDlH;AAMD,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAE3D;AAgBD,wBAAsB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAMjF;AAED,qFAAqF;AACrF,wBAAsB,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAW7F;AAMD,MAAM,MAAM,YAAY,GAAG,CAAC,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;AAgBjF,wBAAsB,WAAW,CAC/B,GAAG,EAAE,IAAI,CAAC,aAAa,EAAE,MAAM,GAAG,KAAK,CAAC,EACxC,GAAG,EAAE,cAAc,EACnB,SAAS,EAAE,YAAY,GACtB,OAAO,CAAC,aAAa,CAAC,CAuBxB;AAED;;;;GAIG;AACH,qBAAa,eAAe;IAMxB,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,GAAG;IAPtB,OAAO,CAAC,QAAQ,CAA6B;IAC7C,OAAO,CAAC,QAAQ,CAAK;IACrB,OAAO,CAAC,IAAI,CAA8B;gBAGvB,IAAI,EAAE,MAAM,OAAO,CAAC,aAAa,CAAC,EAClC,SAAS,EAAE,YAAY,EACvB,GAAG,GAAE,MAAM,MAAiB;IAG/C,IAAI,UAAU,IAAI,aAAa,GAAG,IAAI,CAErC;IAEK,MAAM,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAoBhD,4FAA4F;IACtF,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAC,aAAa,EAAE,MAAM,GAAG,KAAK,CAAC,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;CAehG"}

package/dist/webhook-notify.js

@@ -0,0 +1,282 @@
+/**
+ * @fileoverview Webhook notifications (ntfy, Slack, Discord, generic JSON) for the events that
+ * already trigger Web Push, so a headless server can reach a phone without a browser tab or a
+ * push subscription.
+ *
+ * Split in three, so the parts that matter are testable without a network:
+ *   - pure: `webhookUrlProblem`, `maskWebhookUrl`, `shouldSendWebhook`, `buildWebhookRequest`
+ *   - store: `~/.codeman/webhook.json`, written 0600 via tmp+rename (the URL is a bearer secret:
+ *     anyone holding a Slack/Discord webhook URL can post as it)
+ *   - IO: `sendWebhook` (injected fetch) and `WebhookNotifier` (dedupe, in-flight cap, last result)
+ *
+ * Rules the code keeps and the tests pin:
+ *   - The URL is configured only through the admin-only `/api/webhook` routes and kept OUT of
+ *     `settings.json`, which every logged-in user can read through `GET /api/settings`.
+ *   - Delivery goes through `webviewFetch`: link-local and cloud-metadata targets are refused on
+ *     the RESOLVED address at connect time, redirects are not followed, and the call is bounded
+ *     by a timeout. Loopback and LAN stay allowed on purpose (a local ntfy is the feature).
+ *   - The URL never appears in a log line, a result, or an error message.
+ *   - Session names and error text are user/agent-controlled, so they cannot ping a channel:
+ *     Discord gets `allowed_mentions: { parse: [] }` and Slack control characters are escaped.
+ *
+ * @module webhook-notify
+ */
+import { existsSync, mkdirSync } from 'node:fs';
+import fs from 'node:fs/promises';
+import { join } from 'node:path';
+import { blockedWebviewHostReason } from './web/webview-egress-policy.js';
+import { isEgressBlockedError } from './web/webview-egress.js';
+import { WEBHOOK_KINDS, WEBHOOK_SCOPES, } from './types/push.js';
+const WEBHOOK_FILE = 'webhook.json';
+const MAX_URL_LENGTH = 2048;
+const SEND_TIMEOUT_MS = 5000;
+const MAX_BODY_CHARS = 500;
+/** Same event + session within this window is sent once: a flapping prompt must not flood a channel. */
+const DEDUPE_WINDOW_MS = 3000;
+const MAX_IN_FLIGHT = 5;
+export const DEFAULT_WEBHOOK_CONFIG = { enabled: false, kind: 'ntfy', url: '', scope: 'attention' };
+// ---------------------------------------------------------------------------
+// Pure
+// ---------------------------------------------------------------------------
+/** Why `raw` cannot be a webhook URL, or null. Used at save time; delivery re-checks the resolved address. */
+export function webhookUrlProblem(raw) {
+    if (raw.length > MAX_URL_LENGTH)
+        return 'URL is too long';
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        return 'Not a valid URL';
+    }
+    if (url.protocol !== 'https:' && url.protocol !== 'http:')
+        return 'Only http and https URLs are allowed';
+    if (url.username || url.password)
+        return 'Put credentials in the path or a header-less token, not user:password@';
+    const blocked = blockedWebviewHostReason(url.hostname);
+    if (blocked)
+        return `Refused: ${blocked}`;
+    return null;
+}
+/** Scheme + host only: the path and query of a webhook URL are the secret. */
+export function maskWebhookUrl(raw) {
+    try {
+        const url = new URL(raw);
+        return `${url.protocol}//${url.host}/•••`;
+    }
+    catch {
+        return '';
+    }
+}
+export function shouldSendWebhook(cfg, urgency) {
+    if (!cfg.enabled || !cfg.url)
+        return false;
+    return cfg.scope === 'all' || urgency !== 'info';
+}
+const clip = (s, n) => (s.length > n ? `${s.slice(0, n - 1)}…` : s);
+/** A header value must be single-line printable ASCII; anything else goes out RFC 2047 encoded. */
+function headerSafe(value) {
+    const oneLine = value.replace(/[\r\n]+/g, ' ').trim();
+    return /^[\x20-\x7e]*$/.test(oneLine) ? oneLine : `=?UTF-8?B?${Buffer.from(oneLine, 'utf8').toString('base64')}?=`;
+}
+/** Slack parses `<!channel>`, `<@U123>` and `<url|text>`; escaping the three control characters turns them to text. */
+const slackEscape = (s) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+const NTFY_PRIORITY = { critical: '5', warning: '4', info: '3' };
+const NTFY_TAGS = {
+    critical: 'rotating_light',
+    warning: 'bell',
+    info: 'white_check_mark',
+};
+export function buildWebhookRequest(kind, msg, now = new Date()) {
+    const title = clip(msg.title, 120);
+    const body = clip(msg.body, MAX_BODY_CHARS);
+    const prefix = msg.host ? `${clip(msg.host, 60)}: ` : '';
+    switch (kind) {
+        case 'ntfy':
+            return {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'text/plain; charset=utf-8',
+                    Title: headerSafe(`${prefix}${title}`),
+                    Priority: NTFY_PRIORITY[msg.urgency],
+                    Tags: NTFY_TAGS[msg.urgency],
+                },
+                body: body || title,
+            };
+        case 'slack':
+            return {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ text: `*${slackEscape(`${prefix}${title}`)}*${body ? `\n${slackEscape(body)}` : ''}` }),
+            };
+        case 'discord':
+            return {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({
+                    content: clip(`**${prefix}${title}**${body ? `\n${body}` : ''}`, 1900),
+                    // Agent output and session names are not trusted to @everyone a channel.
+                    allowed_mentions: { parse: [] },
+                }),
+            };
+        case 'generic':
+            return {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({
+                    event: msg.event,
+                    title,
+                    body,
+                    urgency: msg.urgency,
+                    sessionId: msg.sessionId ?? null,
+                    sessionName: msg.sessionName ?? null,
+                    host: msg.host ?? null,
+                    at: now.toISOString(),
+                }),
+            };
+    }
+}
+// ---------------------------------------------------------------------------
+// Store
+// ---------------------------------------------------------------------------
+export function webhookConfigPath(configDir) {
+    return join(configDir, WEBHOOK_FILE);
+}
+function coerce(raw) {
+    const r = (typeof raw === 'object' && raw !== null ? raw : {});
+    return {
+        enabled: r.enabled === true,
+        kind: WEBHOOK_KINDS.includes(r.kind)
+            ? r.kind
+            : DEFAULT_WEBHOOK_CONFIG.kind,
+        url: typeof r.url === 'string' ? r.url : '',
+        scope: WEBHOOK_SCOPES.includes(r.scope)
+            ? r.scope
+            : DEFAULT_WEBHOOK_CONFIG.scope,
+    };
+}
+export async function readWebhookConfig(configDir) {
+    try {
+        return coerce(JSON.parse(await fs.readFile(webhookConfigPath(configDir), 'utf-8')));
+    }
+    catch {
+        return { ...DEFAULT_WEBHOOK_CONFIG };
+    }
+}
+/** 0600 via tmp+rename: `mode` on writeFile only applies to a file being created. */
+export async function writeWebhookConfig(configDir, cfg) {
+    if (!existsSync(configDir))
+        mkdirSync(configDir, { recursive: true });
+    const target = webhookConfigPath(configDir);
+    const tmp = `${target}.${process.pid}.tmp`;
+    try {
+        await fs.writeFile(tmp, JSON.stringify(coerce(cfg), null, 2), { mode: 0o600 });
+        await fs.rename(tmp, target);
+    }
+    catch (err) {
+        await fs.unlink(tmp).catch(() => undefined);
+        throw err;
+    }
+}
+/**
+ * What went wrong, without the URL: blocked / timed out / refused / an HTTP status. An egress
+ * refusal is recognised by its `CODEMAN_EGRESS_BLOCKED` code anywhere in the cause chain (undici
+ * wraps the lookup's error as `TypeError('fetch failed', { cause })`), never by message text.
+ */
+function describeError(err) {
+    const e = err;
+    if (e?.name === 'TimeoutError' || e?.name === 'AbortError')
+        return 'Timed out';
+    if (isEgressBlockedError(err))
+        return 'Refused: target is a link-local or cloud-metadata address';
+    if (e?.cause?.code === 'ENOTFOUND')
+        return 'Host not found';
+    if (e?.cause?.code === 'ECONNREFUSED')
+        return 'Connection refused';
+    return 'Network error';
+}
+export async function sendWebhook(cfg, msg, fetchImpl) {
+    const at = Date.now();
+    const problem = webhookUrlProblem(cfg.url);
+    if (problem)
+        return { ok: false, error: problem, at };
+    const req = buildWebhookRequest(cfg.kind, msg);
+    try {
+        const res = await fetchImpl(new URL(cfg.url), {
+            method: req.method,
+            headers: req.headers,
+            body: req.body,
+            redirect: 'manual',
+            signal: AbortSignal.timeout(SEND_TIMEOUT_MS),
+        });
+        void res.body?.cancel().catch(() => undefined);
+        if (res.status >= 300 && res.status < 400) {
+            return { ok: false, status: res.status, error: 'The URL redirects; use the final URL', at };
+        }
+        return res.ok
+            ? { ok: true, status: res.status, at }
+            : { ok: false, status: res.status, error: `HTTP ${res.status}`, at };
+    }
+    catch (err) {
+        return { ok: false, error: describeError(err), at };
+    }
+}
+/**
+ * Sends the notifications the server decides on. Fire-and-forget by design (a slow webhook must
+ * never delay Web Push or a request), so it dedupes, caps what is in flight, and remembers only
+ * the last result for the Settings status line.
+ */
+export class WebhookNotifier {
+    load;
+    fetchImpl;
+    now;
+    lastSent = new Map();
+    inFlight = 0;
+    last = null;
+    constructor(load, fetchImpl, now = Date.now) {
+        this.load = load;
+        this.fetchImpl = fetchImpl;
+        this.now = now;
+    }
+    get lastResult() {
+        return this.last;
+    }
+    async notify(msg) {
+        const cfg = await this.load();
+        if (!shouldSendWebhook(cfg, msg.urgency))
+            return;
+        const key = `${msg.event}:${msg.sessionId ?? ''}`;
+        const t = this.now();
+        const prev = this.lastSent.get(key);
+        if (prev !== undefined && t - prev < DEDUPE_WINDOW_MS)
+            return;
+        if (this.inFlight >= MAX_IN_FLIGHT)
+            return;
+        this.lastSent.set(key, t);
+        if (this.lastSent.size > 256) {
+            for (const [k, v] of this.lastSent)
+                if (t - v > DEDUPE_WINDOW_MS)
+                    this.lastSent.delete(k);
+        }
+        this.inFlight++;
+        try {
+            this.last = await sendWebhook(cfg, msg, this.fetchImpl);
+        }
+        finally {
+            this.inFlight--;
+        }
+    }
+    /** A deliberate test send: bypasses `enabled`, scope and dedupe, and records the result. */
+    async sendTest(cfg, host) {
+        const result = await sendWebhook(cfg, {
+            event: 'webhook:test',
+            title: 'Codeman test notification',
+            body: 'If you can read this, webhook notifications are working.',
+            urgency: 'info',
+            host,
+        }, this.fetchImpl);
+        this.last = result;
+        return result;
+    }
+}
+//# sourceMappingURL=webhook-notify.js.map

package/dist/webhook-notify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook-notify.js","sourceRoot":"","sources":["../src/webhook-notify.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aicodeman",
-  "version": "1.33.2",
+  "version": "1.34.0",
   "description": "Mission control for AI coding agents - run 20 autonomous agents with real-time monitoring and session persistence",
   "type": "module",
   "main": "dist/index.js",
@@ -105,6 +105,7 @@
     "jpeg-js": "^0.4.4",
     "node-pty": "^1.1.0",
     "qrcode": "^1.5.4",
+    "smol-toml": "^1.9.0",
     "undici": "^6.28.0",
     "uuid": "^14.0.0",
     "web-push": "^3.6.7",

package/skills/codeman/SKILL.md

@@ -47,7 +47,7 @@ later call opens with, and your first REAL call performs them anyway:
 
 ```bash
 . "${XDG_CACHE_HOME:-$HOME/.cache}/codeman-agent-$CODEMAN_SESSION_ID.sh" 2>/dev/null
-[ "${CODEMAN_PREAMBLE:-}" = 1.30.1 ] || { echo "preamble missing or stale; run the full §0 block"; exit 1; }
+[ "${CODEMAN_PREAMBLE:-}" = 1.33.4 ] || { echo "preamble missing or stale; run the full §0 block"; exit 1; }
 ```
 
 ⚠️ **Never spend a Bash call on this check alone.** §1's block opens with this same
@@ -75,8 +75,8 @@ PRE="${XDG_CACHE_HOME:-$HOME/.cache}/codeman-agent-$CODEMAN_SESSION_ID.sh"
 mkdir -p "$(dirname "$PRE")"
 # Rewrite unless the file already ends with THIS version's stamp, so a stale or a
 # half-written file self-heals here instead of costing you a round trip to rm it.
-grep -qs '^CODEMAN_PREAMBLE=1.30.1$' "$PRE" || (umask 077; cat > "$PRE" <<'PREAMBLE'
-# ---- Codeman agent preamble 1.30.1 (seeded by Codeman at session spawn; the SKILL.md §0 bootstrap rewrites it when missing or stale) ----
+grep -qs '^CODEMAN_PREAMBLE=1.33.4$' "$PRE" || (umask 077; cat > "$PRE" <<'PREAMBLE'
+# ---- Codeman agent preamble 1.33.4 (seeded by Codeman at session spawn; the SKILL.md §0 bootstrap rewrites it when missing or stale) ----
 API="${CODEMAN_API_URL:?CODEMAN_API_URL not set; refusing to guess}"
 SELF="${CODEMAN_SESSION_ID:?CODEMAN_SESSION_ID not set}"
 # Credentials, cheapest first. Your session has usually INHERITED the server's
@@ -196,6 +196,11 @@ _accept_trust() {  # <sid> -> 0 once it has answered the dialog, 1 if it could n
 # rather than handed back, because a worker that never drew its composer would eat the
 # task prompt with its trust dialog. There is deliberately no pid poll: wait-output
 # already blocks until the composer draws, and pid!=null proved startup, never readiness.
+# CODEMAN_WORKER_ADVISOR=opus (or fable / sonnet) gives every CLAUDE worker spawned while
+# it is set Claude Code's advisor tool: a stronger model the worker consults before
+# committing to an approach, on a recurring error and before declaring the task done.
+# Other modes ignore it. A value the server refuses fails the spawn (INVALID_INPUT); an
+# advisor that ranks below the worker's model is accepted but never attached by claude.
 spawn_worker() {
   local name="${1:?spawn_worker needs a case name}" mode="${2:-claude}" q sid cp r
   # parentSessionId doubles the CURL header, so a spawn_worker copied off the shared
@@ -207,12 +212,19 @@ spawn_worker() {
   # server clamps this back to `workspace-write` for an owner without the grant.
   # Spawn by hand (§5.1) when you want a worker that asks.
   q=$("${CURL[@]}" -X POST "$API/api/v1/quick-start" -H 'Content-Type: application/json' \
-      -d "$(jq -nc --arg n "$name" --arg m "$mode" --arg p "$SELF" \
+      -d "$(jq -nc --arg n "$name" --arg m "$mode" --arg p "$SELF" --arg a "${CODEMAN_WORKER_ADVISOR:-}" \
         '{caseName:$n,mode:$m,parentSessionId:$p}
-         + (if $m == "deepseek" then {deepSeekConfig:{permissionMode:"danger-full-access"}} else {} end)')")
+         + (if $m == "deepseek" then {deepSeekConfig:{permissionMode:"danger-full-access"}} else {} end)
+         + (if $m == "claude" and $a != "" then {advisorModel:$a} else {} end)')")
   sid=$(jq -r 'if .success then .data.sessionId else empty end' <<<"$q")
   # NOT retryable in a loop: every quick-start failure code is terminal (§5.1).
   [ -n "$sid" ] || { jq -c '{error,errorCode}' <<<"$q" >&2; return 1; }
+  # A server without advisor support DROPS the field instead of refusing it, so read it
+  # back: a worker silently missing the advisor it was asked for is worth one line.
+  if [ "$mode" = claude ] && [ -n "${CODEMAN_WORKER_ADVISOR:-}" ] &&
+     [ "$("${CURL[@]}" "$API/api/v1/sessions/$sid" | jq -r '.data.advisorModel // empty')" != "$CODEMAN_WORKER_ADVISOR" ]; then
+    echo "worker $sid: this Codeman server ignored CODEMAN_WORKER_ADVISOR (no advisor support); it runs without one" >&2
+  fi
   if [ "$mode" = deepseek ]; then
     # The one non-claude mode with REAL end-of-turn signals: its TUI reports
     # idle/working/blocked to Codeman, so sendwait, until=stop and the Approvals
@@ -372,10 +384,10 @@ last_text() {
 # The stamp is the LAST line on purpose (a truncated write leaves it unset) and is kept
 # bare on purpose: the write condition above anchors on it with $, so an inline comment
 # here would fail that match and rewrite this file on every single bootstrap.
-CODEMAN_PREAMBLE=1.30.1
+CODEMAN_PREAMBLE=1.33.4
 PREAMBLE
 )
-. "$PRE"; [ "${CODEMAN_PREAMBLE:-}" = 1.30.1 ] || { echo "preamble at $PRE is stale or truncated: rm it and re-run this block"; exit 1; }
+. "$PRE"; [ "${CODEMAN_PREAMBLE:-}" = 1.33.4 ] || { echo "preamble at $PRE is stale or truncated: rm it and re-run this block"; exit 1; }
 ```
 
 Every later Bash call that touches the API starts with the same two loader lines from
@@ -426,7 +438,7 @@ and no per-call body to hand-build.
 
 ```bash
 . "${XDG_CACHE_HOME:-$HOME/.cache}/codeman-agent-$CODEMAN_SESSION_ID.sh" 2>/dev/null   # §0 loader
-[ "${CODEMAN_PREAMBLE:-}" = 1.30.1 ] || { echo "preamble missing or stale; run the full §0 block"; exit 1; }
+[ "${CODEMAN_PREAMBLE:-}" = 1.33.4 ] || { echo "preamble missing or stale; run the full §0 block"; exit 1; }
 N=(alpha beta)                    # INVENT one fresh case name per worker; never list cases first
                                   # (a name may carry a mode: `beta:deepseek`, see below)
 T=('reply with one line: the absolute path of your working directory'
@@ -493,6 +505,12 @@ Four things this block leans on, each one link away, no detour needed to run it:
   `sendwait` reads the composer and keeps pressing Enter until the prompt has left it.
   All three are reasons to let `sendwait` build the call rather than hand-rolling it.
 - Each `sendwait` costs that worker one billed turn, as does every prompt you send it.
+- For long or high-stakes worker tasks, `CODEMAN_WORKER_ADVISOR=opus spawn_workers "${N[@]}"`
+  (`fable`, `opus` or `sonnet`) gives each claude worker Claude Code's advisor tool: a
+  stronger model it consults before committing to an approach, on a recurring error and
+  before declaring the task done. Advisor calls bill extra tokens, and an advisor ranked
+  below the worker's own model is never attached (on an Opus worker only `opus` and
+  `fable` do anything).
 - Deleting the sessions does **not** remove the case directories. They are marked as
   agent-created, so `GET /api/v1/cases/agent-created` lists them for cleanup: §5.14.
 

package/skills/codeman/preamble.sh

@@ -1,4 +1,4 @@
-# ---- Codeman agent preamble 1.30.1 (seeded by Codeman at session spawn; the SKILL.md §0 bootstrap rewrites it when missing or stale) ----
+# ---- Codeman agent preamble 1.33.4 (seeded by Codeman at session spawn; the SKILL.md §0 bootstrap rewrites it when missing or stale) ----
 API="${CODEMAN_API_URL:?CODEMAN_API_URL not set; refusing to guess}"
 SELF="${CODEMAN_SESSION_ID:?CODEMAN_SESSION_ID not set}"
 # Credentials, cheapest first. Your session has usually INHERITED the server's
@@ -118,6 +118,11 @@ _accept_trust() {  # <sid> -> 0 once it has answered the dialog, 1 if it could n
 # rather than handed back, because a worker that never drew its composer would eat the
 # task prompt with its trust dialog. There is deliberately no pid poll: wait-output
 # already blocks until the composer draws, and pid!=null proved startup, never readiness.
+# CODEMAN_WORKER_ADVISOR=opus (or fable / sonnet) gives every CLAUDE worker spawned while
+# it is set Claude Code's advisor tool: a stronger model the worker consults before
+# committing to an approach, on a recurring error and before declaring the task done.
+# Other modes ignore it. A value the server refuses fails the spawn (INVALID_INPUT); an
+# advisor that ranks below the worker's model is accepted but never attached by claude.
 spawn_worker() {
   local name="${1:?spawn_worker needs a case name}" mode="${2:-claude}" q sid cp r
   # parentSessionId doubles the CURL header, so a spawn_worker copied off the shared
@@ -129,12 +134,19 @@ spawn_worker() {
   # server clamps this back to `workspace-write` for an owner without the grant.
   # Spawn by hand (§5.1) when you want a worker that asks.
   q=$("${CURL[@]}" -X POST "$API/api/v1/quick-start" -H 'Content-Type: application/json' \
-      -d "$(jq -nc --arg n "$name" --arg m "$mode" --arg p "$SELF" \
+      -d "$(jq -nc --arg n "$name" --arg m "$mode" --arg p "$SELF" --arg a "${CODEMAN_WORKER_ADVISOR:-}" \
         '{caseName:$n,mode:$m,parentSessionId:$p}
-         + (if $m == "deepseek" then {deepSeekConfig:{permissionMode:"danger-full-access"}} else {} end)')")
+         + (if $m == "deepseek" then {deepSeekConfig:{permissionMode:"danger-full-access"}} else {} end)
+         + (if $m == "claude" and $a != "" then {advisorModel:$a} else {} end)')")
   sid=$(jq -r 'if .success then .data.sessionId else empty end' <<<"$q")
   # NOT retryable in a loop: every quick-start failure code is terminal (§5.1).
   [ -n "$sid" ] || { jq -c '{error,errorCode}' <<<"$q" >&2; return 1; }
+  # A server without advisor support DROPS the field instead of refusing it, so read it
+  # back: a worker silently missing the advisor it was asked for is worth one line.
+  if [ "$mode" = claude ] && [ -n "${CODEMAN_WORKER_ADVISOR:-}" ] &&
+     [ "$("${CURL[@]}" "$API/api/v1/sessions/$sid" | jq -r '.data.advisorModel // empty')" != "$CODEMAN_WORKER_ADVISOR" ]; then
+    echo "worker $sid: this Codeman server ignored CODEMAN_WORKER_ADVISOR (no advisor support); it runs without one" >&2
+  fi
   if [ "$mode" = deepseek ]; then
     # The one non-claude mode with REAL end-of-turn signals: its TUI reports
     # idle/working/blocked to Codeman, so sendwait, until=stop and the Approvals
@@ -294,4 +306,4 @@ last_text() {
 # The stamp is the LAST line on purpose (a truncated write leaves it unset) and is kept
 # bare on purpose: the write condition above anchors on it with $, so an inline comment
 # here would fail that match and rewrite this file on every single bootstrap.
-CODEMAN_PREAMBLE=1.30.1
+CODEMAN_PREAMBLE=1.33.4

package/skills/codeman/reference/endpoints.md

@@ -345,6 +345,13 @@ ESC=$(printf '\033')
 `.data.{sessionId, caseName, casePath}`. Creates the case directory (a real directory
 on the user's disk) if missing, do not retry it in a loop, and remember the name.
 
+A claude worker also takes `"advisorModel":"opus"` (`fable`, `opus`, `sonnet` or a full
+model id): Claude Code's advisor tool, a stronger model the worker consults before
+committing to an approach, on a recurring error and before declaring the task done. It is
+a soft default the worker can change with `/advisor`. Remote and docker cases refuse it
+(400), as they refuse `effort`. `spawn_worker` and `spawn_workers` send it for you when
+`CODEMAN_WORKER_ADVISOR` is set.
+
 ⚠️ A `mode` whose CLI is **not installed on the server** fails the spawn with
 `OPERATION_FAILED`; it never falls back to claude. Probe first whenever you did not pick
 the mode yourself: `GET /api/v1/claude/status`, `GET /api/v1/opencode/status`,
@@ -384,17 +391,18 @@ every claude create path installs them, so a linked case and a raw path both get
 
 **The two-step alternative, `POST /api/v1/sessions`.** Use it when you need a session in
 a directory that is not a case (body takes `workingDir`, `mode`, `name`, `effort`,
-`envOverrides`). Three differences that break copied code:
+`advisorModel`, `envOverrides`, and for claude a per-session `model` passed as `--model`). Three
+differences that break copied code:
 
 - The id is at **`.data.session.id`**, not quick-start's `.data.sessionId`
-  (`session-routes.ts:878` returns `{ session: lightState }`).
+  (the `POST /api/sessions` handler in `session-routes.ts` returns `{ session: lightState }`).
 - **It spawns no PTY.** The session exists with `pid:null` and nothing running, so
   `wait?until=exit` answers `exit` immediately. Follow it with
   `POST /api/v1/sessions/:id/interactive` (claude and the other agent CLIs) or
   `POST /api/v1/sessions/:id/shell` (shell mode) to actually start the worker.
 - Its capacity failure is **`OPERATION_FAILED` (422)**, not quick-start's
   `SESSION_BUSY` (409), from the same global-50 / per-user-25 caps
-  (`session-routes.ts:648`).
+  (`sessionCapacityMessage()` in `route-helpers.ts`).
 
 ⚠️ `POST .../interactive` accepts `{"clearBreaker":true}`, which resets the **PTY-exit
 circuit breaker**. That breaker exists to stop a session that keeps crashing on spawn

package/skills/codeman/reference/recipes.md

@@ -21,7 +21,7 @@ by sourcing the preamble file the §0 bootstrap wrote, and checking its version
 
 ```bash
 . "${XDG_CACHE_HOME:-$HOME/.cache}/codeman-agent-$CODEMAN_SESSION_ID.sh" 2>/dev/null
-[ "${CODEMAN_PREAMBLE:-}" = 1.30.1 ] || { echo "preamble missing or stale; re-run the §0 bootstrap"; exit 1; }
+[ "${CODEMAN_PREAMBLE:-}" = 1.33.4 ] || { echo "preamble missing or stale; re-run the §0 bootstrap"; exit 1; }
 ```
 
 Do **not** re-paste the preamble body into each call. Sourcing it is what retires the