sequant 2.2.0 → 2.3.0

package/dist/src/lib/relay/pid.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Per-issue PID tracking for relay liveness checks (AC-20/21/22).
+ *
+ * Reuses `defaultIsPidAlive` from `LockManager` — no duplicate `kill(pid, 0)`
+ * implementations (AC-21).
+ */
+/** Re-export so callers don't need to import from `locks` directly. */
+export { defaultIsPidAlive as isPidAlive } from "../locks/lock-manager.js";
+/** Write `<cwd>/.sequant/pids/<issue>.pid` containing the current PID. */
+export declare function writePidFile(issue: number, pid?: number, cwd?: string): string;
+/** Read the PID stored in the pidfile. Returns `null` if missing/unparseable. */
+export declare function readPidFile(issue: number, cwd?: string): number | null;
+/** Remove the pidfile for an issue if it exists. */
+export declare function removePidFile(issue: number, cwd?: string): boolean;
+export interface StaleCleanupResult {
+    /** Was a stale pidfile removed? */
+    cleaned: boolean;
+    /** Is the run still alive? */
+    alive: boolean;
+    /** PID we observed, if any. */
+    pid: number | null;
+    /** Human warning when a stale entry was cleared. */
+    warning: string | null;
+}
+/**
+ * Inspect the pidfile and clean it up if the PID is dead.
+ *
+ * Returns a structured result so callers can decide what to do (e.g.
+ * `sequant prompt` refuses to send to a dead run; warn the user).
+ */
+export declare function cleanupStalePid(issue: number, options?: {
+    cwd?: string;
+    isAlive?: (pid: number) => boolean;
+}): StaleCleanupResult;

package/dist/src/lib/relay/pid.js

@@ -0,0 +1,72 @@
+/**
+ * Per-issue PID tracking for relay liveness checks (AC-20/21/22).
+ *
+ * Reuses `defaultIsPidAlive` from `LockManager` — no duplicate `kill(pid, 0)`
+ * implementations (AC-21).
+ */
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync, } from "fs";
+import { dirname } from "path";
+import { defaultIsPidAlive } from "../locks/lock-manager.js";
+import { pidPathFor } from "./paths.js";
+/** Re-export so callers don't need to import from `locks` directly. */
+export { defaultIsPidAlive as isPidAlive } from "../locks/lock-manager.js";
+/** Write `<cwd>/.sequant/pids/<issue>.pid` containing the current PID. */
+export function writePidFile(issue, pid = process.pid, cwd = process.cwd()) {
+    const path = pidPathFor(issue, cwd);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, String(pid), "utf-8");
+    return path;
+}
+/** Read the PID stored in the pidfile. Returns `null` if missing/unparseable. */
+export function readPidFile(issue, cwd = process.cwd()) {
+    const path = pidPathFor(issue, cwd);
+    if (!existsSync(path))
+        return null;
+    try {
+        const raw = readFileSync(path, "utf-8").trim();
+        const pid = Number.parseInt(raw, 10);
+        if (!Number.isInteger(pid) || pid <= 0)
+            return null;
+        return pid;
+    }
+    catch {
+        return null;
+    }
+}
+/** Remove the pidfile for an issue if it exists. */
+export function removePidFile(issue, cwd = process.cwd()) {
+    const path = pidPathFor(issue, cwd);
+    if (!existsSync(path))
+        return false;
+    try {
+        unlinkSync(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Inspect the pidfile and clean it up if the PID is dead.
+ *
+ * Returns a structured result so callers can decide what to do (e.g.
+ * `sequant prompt` refuses to send to a dead run; warn the user).
+ */
+export function cleanupStalePid(issue, options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const alive = options.isAlive ?? defaultIsPidAlive;
+    const pid = readPidFile(issue, cwd);
+    if (pid === null) {
+        return { cleaned: false, alive: false, pid: null, warning: null };
+    }
+    if (alive(pid)) {
+        return { cleaned: false, alive: true, pid, warning: null };
+    }
+    removePidFile(issue, cwd);
+    return {
+        cleaned: true,
+        alive: false,
+        pid,
+        warning: `Run for #${issue} is no longer active (process exited). Message not sent.`,
+    };
+}

package/dist/src/lib/relay/reader.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Reader for the relay inbox. Tracks the last-read line via a `.cursor` file
+ * so each PostToolUse hook invocation only sees new messages (AC-11).
+ *
+ * Atomic cursor update: write to a temp file in the same directory, then
+ * rename. A crash mid-write never leaves a half-written cursor.
+ */
+import { type RelayMessage } from "./types.js";
+import { type RelayPathOptions } from "./paths.js";
+export interface ReadResult {
+    /** Newly read inbox messages, ordered by file appearance (timestamp). */
+    messages: RelayMessage[];
+    /** Cursor value after this read. */
+    cursor: number;
+    /** Total line count of inbox.jsonl after the read. */
+    inboxLineCount: number;
+    /** Malformed lines that were skipped (for logging). */
+    skipped: number;
+}
+/** Read the persisted cursor; missing/unparseable → 0 (AC-11 edge case). */
+export declare function readCursor(issue: number, options?: RelayPathOptions): number;
+/** Write the cursor atomically (temp file + rename). */
+export declare function writeCursor(issue: number, value: number, options?: RelayPathOptions): void;
+/**
+ * Read unread inbox messages and advance the cursor.
+ *
+ * - Missing or empty inbox → empty result (fast path).
+ * - Malformed JSON lines are logged via the `onMalformed` callback (if any)
+ *   and skipped; the cursor still advances past them so we don't loop.
+ * - If the cursor points past EOF (inbox was truncated/rotated), reset to the
+ *   current line count and return no messages.
+ */
+export declare function readUnreadMessages(issue: number, options?: RelayPathOptions & {
+    onMalformed?: (line: string, index: number) => void;
+}): ReadResult;

package/dist/src/lib/relay/reader.js

@@ -0,0 +1,115 @@
+/**
+ * Reader for the relay inbox. Tracks the last-read line via a `.cursor` file
+ * so each PostToolUse hook invocation only sees new messages (AC-11).
+ *
+ * Atomic cursor update: write to a temp file in the same directory, then
+ * rename. A crash mid-write never leaves a half-written cursor.
+ */
+import { randomBytes } from "crypto";
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, statSync, unlinkSync, writeSync, } from "fs";
+import { dirname, join } from "path";
+import { RelayMessageSchema } from "./types.js";
+import { cursorPathFor, inboxPathFor } from "./paths.js";
+/** Read the persisted cursor; missing/unparseable → 0 (AC-11 edge case). */
+export function readCursor(issue, options = {}) {
+    const path = cursorPathFor(issue, options);
+    if (!existsSync(path))
+        return 0;
+    try {
+        const raw = readFileSync(path, "utf-8").trim();
+        const n = Number.parseInt(raw, 10);
+        if (!Number.isInteger(n) || n < 0)
+            return 0;
+        return n;
+    }
+    catch {
+        return 0;
+    }
+}
+/** Write the cursor atomically (temp file + rename). */
+export function writeCursor(issue, value, options = {}) {
+    const path = cursorPathFor(issue, options);
+    mkdirSync(dirname(path), { recursive: true });
+    const tmp = join(dirname(path), `.cursor.${process.pid}.${Date.now()}.${randomBytes(2).toString("hex")}.tmp`);
+    try {
+        const fd = openSync(tmp, "w");
+        try {
+            writeSync(fd, String(value));
+        }
+        finally {
+            closeSync(fd);
+        }
+        renameSync(tmp, path);
+    }
+    catch (err) {
+        if (existsSync(tmp)) {
+            try {
+                unlinkSync(tmp);
+            }
+            catch {
+                /* swallow */
+            }
+        }
+        throw err;
+    }
+}
+/**
+ * Read unread inbox messages and advance the cursor.
+ *
+ * - Missing or empty inbox → empty result (fast path).
+ * - Malformed JSON lines are logged via the `onMalformed` callback (if any)
+ *   and skipped; the cursor still advances past them so we don't loop.
+ * - If the cursor points past EOF (inbox was truncated/rotated), reset to the
+ *   current line count and return no messages.
+ */
+export function readUnreadMessages(issue, options = {}) {
+    const inboxPath = inboxPathFor(issue, options);
+    if (!existsSync(inboxPath)) {
+        return { messages: [], cursor: 0, inboxLineCount: 0, skipped: 0 };
+    }
+    const st = statSync(inboxPath);
+    if (st.size === 0) {
+        return { messages: [], cursor: 0, inboxLineCount: 0, skipped: 0 };
+    }
+    const text = readFileSync(inboxPath, "utf-8");
+    const lines = text.split("\n").filter((l, idx, arr) => {
+        // Keep all but the final empty element from a trailing newline.
+        return !(idx === arr.length - 1 && l === "");
+    });
+    const totalLines = lines.length;
+    let cursor = readCursor(issue, options);
+    // If cursor is past EOF (file was rotated/truncated), reset to current end.
+    if (cursor > totalLines) {
+        writeCursor(issue, totalLines, options);
+        return {
+            messages: [],
+            cursor: totalLines,
+            inboxLineCount: totalLines,
+            skipped: 0,
+        };
+    }
+    const messages = [];
+    let skipped = 0;
+    for (let i = cursor; i < totalLines; i++) {
+        const raw = lines[i];
+        if (raw.trim() === "")
+            continue;
+        try {
+            const obj = JSON.parse(raw);
+            const parsed = RelayMessageSchema.safeParse(obj);
+            if (!parsed.success) {
+                skipped++;
+                options.onMalformed?.(raw, i);
+                continue;
+            }
+            messages.push(parsed.data);
+        }
+        catch {
+            skipped++;
+            options.onMalformed?.(raw, i);
+        }
+    }
+    cursor = totalLines;
+    writeCursor(issue, cursor, options);
+    return { messages, cursor, inboxLineCount: totalLines, skipped };
+}

package/dist/src/lib/relay/types.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Type definitions and Zod schemas for the interactive relay (#383).
+ *
+ * The relay is a file-based IPC channel that allows a user terminal to send
+ * messages into a running headless Claude session. Messages flow through two
+ * JSONL files in `<worktree>/.sequant/relay/`:
+ *
+ *  - `inbox.jsonl`: user → Claude (consumed by the PostToolUse hook)
+ *  - `outbox.jsonl`: Claude → user (tailed by `sequant watch`)
+ */
+import { z } from "zod";
+/** Maximum size (bytes) of a single relay message body. */
+export declare const MAX_MESSAGE_BYTES: number;
+/** Relay message types. `query` asks for status, `directive` nudges behavior, `abort` stops. */
+export declare const RelayMessageTypeSchema: z.ZodEnum<{
+    abort: "abort";
+    query: "query";
+    directive: "directive";
+}>;
+export type RelayMessageType = z.infer<typeof RelayMessageTypeSchema>;
+/** Inbox message id format: `msg_<hex>`. */
+export declare const MESSAGE_ID_PATTERN: RegExp;
+/** Outbox reply id format: `reply_<hex>`. */
+export declare const REPLY_ID_PATTERN: RegExp;
+/**
+ * Discriminated union over `type`. `query` and `directive` require a non-empty
+ * `message` body; `abort` allows an optional explanatory message but it is not
+ * required.
+ */
+export declare const RelayMessageSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"query">;
+    message: z.ZodString;
+    id: z.ZodString;
+    timestamp: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"directive">;
+    message: z.ZodString;
+    id: z.ZodString;
+    timestamp: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"abort">;
+    message: z.ZodOptional<z.ZodString>;
+    id: z.ZodString;
+    timestamp: z.ZodString;
+}, z.core.$strip>], "type">;
+export type RelayMessage = z.infer<typeof RelayMessageSchema>;
+/** Outbox reply. `inReplyTo` is mandatory — every reply references an inbox id. */
+export declare const RelayResponseSchema: z.ZodObject<{
+    id: z.ZodString;
+    inReplyTo: z.ZodString;
+    timestamp: z.ZodString;
+    message: z.ZodString;
+}, z.core.$strip>;
+export type RelayResponse = z.infer<typeof RelayResponseSchema>;
+export { RelayStateSchema, type RelayState } from "../workflow/state-schema.js";
+/**
+ * `meta.json` written alongside archived inbox/outbox in
+ * `.sequant/logs/relay/<issue>-<phase>-<ts>/`. Captures the run boundary so
+ * post-hoc inspection knows which phase/issue the messages belonged to.
+ */
+export declare const RelayArchiveMetaSchema: z.ZodObject<{
+    issue: z.ZodNumber;
+    phase: z.ZodString;
+    startedAt: z.ZodString;
+    endedAt: z.ZodString;
+    messageCount: z.ZodNumber;
+}, z.core.$strip>;
+export type RelayArchiveMeta = z.infer<typeof RelayArchiveMetaSchema>;

package/dist/src/lib/relay/types.js

@@ -0,0 +1,76 @@
+/**
+ * Type definitions and Zod schemas for the interactive relay (#383).
+ *
+ * The relay is a file-based IPC channel that allows a user terminal to send
+ * messages into a running headless Claude session. Messages flow through two
+ * JSONL files in `<worktree>/.sequant/relay/`:
+ *
+ *  - `inbox.jsonl`: user → Claude (consumed by the PostToolUse hook)
+ *  - `outbox.jsonl`: Claude → user (tailed by `sequant watch`)
+ */
+import { z } from "zod";
+/** Maximum size (bytes) of a single relay message body. */
+export const MAX_MESSAGE_BYTES = 16 * 1024; // 16 KB
+/** Relay message types. `query` asks for status, `directive` nudges behavior, `abort` stops. */
+export const RelayMessageTypeSchema = z.enum(["query", "directive", "abort"]);
+/** Inbox message id format: `msg_<hex>`. */
+export const MESSAGE_ID_PATTERN = /^msg_[0-9a-f]+$/;
+/** Outbox reply id format: `reply_<hex>`. */
+export const REPLY_ID_PATTERN = /^reply_[0-9a-f]+$/;
+const baseInboxFields = {
+    id: z.string().regex(MESSAGE_ID_PATTERN, "id must match /^msg_[0-9a-f]+$/"),
+    timestamp: z.string().datetime(),
+};
+/**
+ * Discriminated union over `type`. `query` and `directive` require a non-empty
+ * `message` body; `abort` allows an optional explanatory message but it is not
+ * required.
+ */
+export const RelayMessageSchema = z.discriminatedUnion("type", [
+    z.object({
+        ...baseInboxFields,
+        type: z.literal("query"),
+        message: z
+            .string()
+            .min(1, "message is required for query")
+            .max(MAX_MESSAGE_BYTES, `message exceeds ${MAX_MESSAGE_BYTES} bytes`),
+    }),
+    z.object({
+        ...baseInboxFields,
+        type: z.literal("directive"),
+        message: z
+            .string()
+            .min(1, "message is required for directive")
+            .max(MAX_MESSAGE_BYTES, `message exceeds ${MAX_MESSAGE_BYTES} bytes`),
+    }),
+    z.object({
+        ...baseInboxFields,
+        type: z.literal("abort"),
+        message: z.string().max(MAX_MESSAGE_BYTES).optional(),
+    }),
+]);
+/** Outbox reply. `inReplyTo` is mandatory — every reply references an inbox id. */
+export const RelayResponseSchema = z.object({
+    id: z.string().regex(REPLY_ID_PATTERN, "id must match /^reply_[0-9a-f]+$/"),
+    inReplyTo: z
+        .string()
+        .min(1, "inReplyTo is required")
+        .regex(MESSAGE_ID_PATTERN, "inReplyTo must match /^msg_[0-9a-f]+$/"),
+    timestamp: z.string().datetime(),
+    message: z.string(),
+});
+// `RelayState` is defined in `src/lib/workflow/state-schema.ts` (canonical
+// location alongside `IssueState`). Re-exported here as a convenience.
+export { RelayStateSchema } from "../workflow/state-schema.js";
+/**
+ * `meta.json` written alongside archived inbox/outbox in
+ * `.sequant/logs/relay/<issue>-<phase>-<ts>/`. Captures the run boundary so
+ * post-hoc inspection knows which phase/issue the messages belonged to.
+ */
+export const RelayArchiveMetaSchema = z.object({
+    issue: z.number().int().positive(),
+    phase: z.string(),
+    startedAt: z.string().datetime(),
+    endedAt: z.string().datetime(),
+    messageCount: z.number().int().nonnegative(),
+});

package/dist/src/lib/relay/writer.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Append-only writer for relay inbox/outbox JSONL files.
+ *
+ * Single-line appends use `O_APPEND` so concurrent writes interleave cleanly
+ * at the line boundary (POSIX guarantees atomicity for `write()` calls smaller
+ * than `PIPE_BUF`/4 KiB on local filesystems). Multi-line payloads use the
+ * temp-file + `rename()` pattern so partial reads never observe a half-written
+ * file (AC-5).
+ */
+import { type RelayMessage, type RelayMessageType, type RelayResponse } from "./types.js";
+import { type RelayPathOptions } from "./paths.js";
+/** Generate a `msg_<hex>` id with enough entropy to stay unique within a run. */
+export declare function generateMessageId(): string;
+/** Generate a `reply_<hex>` id. */
+export declare function generateReplyId(): string;
+/** Build an inbox message, validating against the schema. */
+export declare function buildInboxMessage(input: {
+    type: RelayMessageType;
+    message?: string;
+    id?: string;
+    timestamp?: string;
+}): RelayMessage;
+/** Build an outbox reply, validating against the schema. */
+export declare function buildOutboxReply(input: {
+    inReplyTo: string;
+    message: string;
+    id?: string;
+    timestamp?: string;
+}): RelayResponse;
+/**
+ * Append a single inbox message. Uses `O_APPEND` for crash-safe concurrent
+ * writes (AC-5). Throws on body sizes that exceed `MAX_MESSAGE_BYTES`.
+ */
+export declare function appendInboxMessage(issue: number, input: {
+    type: RelayMessageType;
+    message?: string;
+}, options?: RelayPathOptions): RelayMessage;
+/** Append a single outbox reply via `O_APPEND`. */
+export declare function appendOutboxReply(issue: number, input: {
+    inReplyTo: string;
+    message: string;
+}, options?: RelayPathOptions): RelayResponse;
+/**
+ * Write multiple inbox messages atomically (temp file + rename).
+ * Useful when seeding a relay dir from a backup or replaying. Single-message
+ * writes should use `appendInboxMessage` instead.
+ */
+export declare function writeInboxBatchAtomic(issue: number, messages: RelayMessage[], options?: RelayPathOptions): void;

package/dist/src/lib/relay/writer.js

@@ -0,0 +1,113 @@
+/**
+ * Append-only writer for relay inbox/outbox JSONL files.
+ *
+ * Single-line appends use `O_APPEND` so concurrent writes interleave cleanly
+ * at the line boundary (POSIX guarantees atomicity for `write()` calls smaller
+ * than `PIPE_BUF`/4 KiB on local filesystems). Multi-line payloads use the
+ * temp-file + `rename()` pattern so partial reads never observe a half-written
+ * file (AC-5).
+ */
+import { randomBytes } from "crypto";
+import { closeSync, existsSync, mkdirSync, openSync, renameSync, unlinkSync, writeSync, } from "fs";
+import { dirname, join } from "path";
+import { MAX_MESSAGE_BYTES, RelayMessageSchema, RelayResponseSchema, } from "./types.js";
+import { inboxPathFor, outboxPathFor } from "./paths.js";
+/** Generate a `msg_<hex>` id with enough entropy to stay unique within a run. */
+export function generateMessageId() {
+    return `msg_${randomBytes(8).toString("hex")}`;
+}
+/** Generate a `reply_<hex>` id. */
+export function generateReplyId() {
+    return `reply_${randomBytes(8).toString("hex")}`;
+}
+function ensureDir(path) {
+    mkdirSync(dirname(path), { recursive: true });
+}
+/** Build an inbox message, validating against the schema. */
+export function buildInboxMessage(input) {
+    const candidate = {
+        id: input.id ?? generateMessageId(),
+        timestamp: input.timestamp ?? new Date().toISOString(),
+        type: input.type,
+        ...(input.message !== undefined ? { message: input.message } : {}),
+    };
+    return RelayMessageSchema.parse(candidate);
+}
+/** Build an outbox reply, validating against the schema. */
+export function buildOutboxReply(input) {
+    return RelayResponseSchema.parse({
+        id: input.id ?? generateReplyId(),
+        inReplyTo: input.inReplyTo,
+        timestamp: input.timestamp ?? new Date().toISOString(),
+        message: input.message,
+    });
+}
+/**
+ * Append a single inbox message. Uses `O_APPEND` for crash-safe concurrent
+ * writes (AC-5). Throws on body sizes that exceed `MAX_MESSAGE_BYTES`.
+ */
+export function appendInboxMessage(issue, input, options = {}) {
+    if (input.message &&
+        Buffer.byteLength(input.message, "utf-8") > MAX_MESSAGE_BYTES) {
+        throw new Error(`relay: message body exceeds max size of ${MAX_MESSAGE_BYTES} bytes`);
+    }
+    const message = buildInboxMessage(input);
+    const path = inboxPathFor(issue, options);
+    appendJsonLine(path, message);
+    return message;
+}
+/** Append a single outbox reply via `O_APPEND`. */
+export function appendOutboxReply(issue, input, options = {}) {
+    const reply = buildOutboxReply(input);
+    const path = outboxPathFor(issue, options);
+    appendJsonLine(path, reply);
+    return reply;
+}
+/**
+ * Write multiple inbox messages atomically (temp file + rename).
+ * Useful when seeding a relay dir from a backup or replaying. Single-message
+ * writes should use `appendInboxMessage` instead.
+ */
+export function writeInboxBatchAtomic(issue, messages, options = {}) {
+    const path = inboxPathFor(issue, options);
+    writeJsonLinesAtomic(path, messages);
+}
+function appendJsonLine(path, payload) {
+    ensureDir(path);
+    const line = JSON.stringify(payload) + "\n";
+    const fd = openSync(path, "a");
+    try {
+        writeSync(fd, line);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+function writeJsonLinesAtomic(path, items) {
+    ensureDir(path);
+    const body = items.map((it) => JSON.stringify(it)).join("\n") +
+        (items.length ? "\n" : "");
+    // Temp file must live on the SAME filesystem as `path` for rename() to be atomic.
+    const tmp = join(dirname(path), `.relay-tmp.${process.pid}.${Date.now()}.${randomBytes(4).toString("hex")}`);
+    try {
+        const fd = openSync(tmp, "w");
+        try {
+            writeSync(fd, body);
+        }
+        finally {
+            closeSync(fd);
+        }
+        renameSync(tmp, path);
+    }
+    catch (err) {
+        if (existsSync(tmp)) {
+            try {
+                unlinkSync(tmp);
+            }
+            catch {
+                /* swallow */
+            }
+        }
+        throw err;
+    }
+}

package/dist/src/lib/settings.d.ts

@@ -42,7 +42,10 @@ export interface AgentSettings {
     /**
      * Default model for sub-agents.
      * Options: "haiku" (cheapest), "sonnet" (balanced), "opus" (most capable)
-     * Default: "haiku"
+     * Default: "haiku" — currently inert per anthropics/claude-code#43869.
+     * @deprecated currently inert; see anthropics/claude-code#43869. Subagents
+     * inherit the parent session's model regardless of this value. Kept so
+     * existing user settings.json files continue to parse without error.
      */
     model: "haiku" | "sonnet" | "opus";
     /**
@@ -144,6 +147,13 @@ export interface RunSettings {
      * Aider-specific configuration. Only used when agent is "aider".
      */
     aider?: AiderSettings;
+    /**
+     * Enable interactive relay (#383): file-based IPC that lets a user terminal
+     * send `query`/`directive`/`abort` messages into a running headless session
+     * via the PostToolUse hook. Disable with `--no-relay`.
+     * Default: true.
+     */
+    relay?: boolean;
 }
 /**
  * Scope assessment threshold configuration
@@ -210,6 +220,20 @@ export interface QASettings {
      * Default: 100
      */
     smallDiffThreshold: number;
+    /**
+     * When a diff touches only markdown files, treat pending CI checks that match
+     * `markdownOnlySafeCiPatterns` as informational instead of forcing
+     * `NEEDS_VERIFICATION`. Failed checks always gate regardless of this setting.
+     * Default: true
+     */
+    markdownOnlyCiRelaxed: boolean;
+    /**
+     * Glob patterns for CI check names that are safe to ignore when pending on a
+     * markdown-only diff (e.g., build matrix, plugin structure validation).
+     * Consumer projects should override these to match their CI step names.
+     * Default: ["build (*)", "Plugin Structure Validation"]
+     */
+    markdownOnlySafeCiPatterns: string[];
 }
 /**
  * Full settings schema
@@ -277,6 +301,7 @@ export declare const RunSettingsSchema: z.ZodObject<{
         editFormat: z.ZodOptional<z.ZodString>;
         extraArgs: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strip>>;
+    relay: z.ZodDefault<z.ZodBoolean>;
 }, z.core.$strip>;
 /** Zod schema for ScopeThreshold (base — fields required, no defaults) */
 export declare const ScopeThresholdSchema: z.ZodObject<{
@@ -318,6 +343,8 @@ export declare const ScopeAssessmentSettingsSchema: z.ZodObject<{
 /** Zod schema for QASettings */
 export declare const QASettingsSchema: z.ZodObject<{
     smallDiffThreshold: z.ZodDefault<z.ZodNumber>;
+    markdownOnlyCiRelaxed: z.ZodDefault<z.ZodBoolean>;
+    markdownOnlySafeCiPatterns: z.ZodDefault<z.ZodArray<z.ZodString>>;
 }, z.core.$strip>;
 /**
  * Zod schema for the full SequantSettings (AC-1, AC-5).
@@ -359,6 +386,7 @@ export declare const SettingsSchema: z.ZodObject<{
             editFormat: z.ZodOptional<z.ZodString>;
             extraArgs: z.ZodOptional<z.ZodArray<z.ZodString>>;
         }, z.core.$strip>>;
+        relay: z.ZodDefault<z.ZodBoolean>;
     }, z.core.$strip>>;
     agents: z.ZodDefault<z.ZodObject<{
         parallel: z.ZodDefault<z.ZodBoolean>;
@@ -397,6 +425,8 @@ export declare const SettingsSchema: z.ZodObject<{
     }, z.core.$strip>>;
     qa: z.ZodDefault<z.ZodObject<{
         smallDiffThreshold: z.ZodDefault<z.ZodNumber>;
+        markdownOnlyCiRelaxed: z.ZodDefault<z.ZodBoolean>;
+        markdownOnlySafeCiPatterns: z.ZodDefault<z.ZodArray<z.ZodString>>;
     }, z.core.$strip>>;
 }, z.core.$loose>;
 /** A single validation warning about an unknown or invalid setting */