sequant 2.2.0 → 2.3.0

package/dist/src/lib/qa/markdown-only-ci.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Markdown-only CI relaxation helpers used by the `/qa` verdict algorithm.
+ *
+ * When a diff touches only documentation/markdown files (no source, no
+ * configuration that affects builds), pending CI checks like the build matrix
+ * cannot meaningfully fail. `/qa` uses these helpers to detect such diffs and
+ * partition pending CI checks into a "relaxed" bucket (informational, does not
+ * gate the verdict) and a "gating" bucket (still gates `READY_FOR_MERGE`).
+ *
+ * Failed CI checks are NOT relaxed — they always gate regardless of diff type.
+ */
+/**
+ * Predicate: does the given changed-file list qualify as a markdown-only diff?
+ *
+ * A file qualifies only if it ends in `.md` (case-insensitive) AND is not
+ * inside `.github/workflows/`. Any non-`.md` file (including `package.json`,
+ * `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`, `tsconfig*.json`, and
+ * `*.config.{js,ts,mjs,cjs}`) automatically disqualifies the diff because it
+ * does not end in `.md`.
+ *
+ * @param files - Paths from `git diff --name-only`. Forward slashes; relative to repo root.
+ * @returns `true` if every changed file is markdown and none are workflow files.
+ */
+export declare function detectMarkdownOnlyDiff(files: string[]): boolean;
+/**
+ * Result of partitioning pending CI checks against the safe-pattern allowlist.
+ */
+export interface RelaxedPendingResult {
+    /** Pending check names that match a safe pattern — informational only. */
+    relaxed: string[];
+    /** Pending check names that do NOT match a safe pattern — still gate the verdict. */
+    gating: string[];
+}
+/**
+ * Partition a list of pending CI check names into "relaxed" (allowlisted) and
+ * "gating" (everything else).
+ *
+ * Patterns support a single `*` wildcard which matches any sequence of
+ * characters (greedy). Special regex characters are otherwise escaped, so
+ * patterns like `build (*)` or `Plugin Structure Validation` work as written.
+ *
+ * @param pendingCheckNames - Names of CI checks currently in a pending state.
+ * @param safePatterns - Glob-like patterns for safe-to-ignore checks.
+ * @returns Buckets for relaxed and gating checks.
+ */
+export declare function filterRelaxablePending(pendingCheckNames: string[], safePatterns: string[]): RelaxedPendingResult;

package/dist/src/lib/qa/markdown-only-ci.js

@@ -0,0 +1,74 @@
+/**
+ * Markdown-only CI relaxation helpers used by the `/qa` verdict algorithm.
+ *
+ * When a diff touches only documentation/markdown files (no source, no
+ * configuration that affects builds), pending CI checks like the build matrix
+ * cannot meaningfully fail. `/qa` uses these helpers to detect such diffs and
+ * partition pending CI checks into a "relaxed" bucket (informational, does not
+ * gate the verdict) and a "gating" bucket (still gates `READY_FOR_MERGE`).
+ *
+ * Failed CI checks are NOT relaxed — they always gate regardless of diff type.
+ */
+/**
+ * Predicate: does the given changed-file list qualify as a markdown-only diff?
+ *
+ * A file qualifies only if it ends in `.md` (case-insensitive) AND is not
+ * inside `.github/workflows/`. Any non-`.md` file (including `package.json`,
+ * `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`, `tsconfig*.json`, and
+ * `*.config.{js,ts,mjs,cjs}`) automatically disqualifies the diff because it
+ * does not end in `.md`.
+ *
+ * @param files - Paths from `git diff --name-only`. Forward slashes; relative to repo root.
+ * @returns `true` if every changed file is markdown and none are workflow files.
+ */
+export function detectMarkdownOnlyDiff(files) {
+    if (files.length === 0)
+        return false;
+    for (const file of files) {
+        if (!file.toLowerCase().endsWith(".md"))
+            return false;
+        if (file.startsWith(".github/workflows/"))
+            return false;
+    }
+    return true;
+}
+/**
+ * Partition a list of pending CI check names into "relaxed" (allowlisted) and
+ * "gating" (everything else).
+ *
+ * Patterns support a single `*` wildcard which matches any sequence of
+ * characters (greedy). Special regex characters are otherwise escaped, so
+ * patterns like `build (*)` or `Plugin Structure Validation` work as written.
+ *
+ * @param pendingCheckNames - Names of CI checks currently in a pending state.
+ * @param safePatterns - Glob-like patterns for safe-to-ignore checks.
+ * @returns Buckets for relaxed and gating checks.
+ */
+export function filterRelaxablePending(pendingCheckNames, safePatterns) {
+    if (safePatterns.length === 0) {
+        return { relaxed: [], gating: [...pendingCheckNames] };
+    }
+    const matchers = safePatterns.map(globToRegex);
+    const relaxed = [];
+    const gating = [];
+    for (const name of pendingCheckNames) {
+        if (matchers.some((re) => re.test(name))) {
+            relaxed.push(name);
+        }
+        else {
+            gating.push(name);
+        }
+    }
+    return { relaxed, gating };
+}
+/**
+ * Translate a single-`*`-wildcard glob into an anchored RegExp.
+ *
+ * `build (*)` → `/^build \(.*\)$/`
+ * `Plugin Structure Validation` → `/^Plugin Structure Validation$/`
+ */
+function globToRegex(pattern) {
+    const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, "\\$&");
+    const wildcarded = escaped.replace(/\*/g, ".*");
+    return new RegExp(`^${wildcarded}$`);
+}

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

@@ -0,0 +1,60 @@
+/**
+ * Relay activation and deactivation lifecycle (#383).
+ *
+ * Activation creates the relay dir, writes the per-issue PID file, and updates
+ * IssueState.relay. Deactivation archives the relay dir (preserving inbox /
+ * outbox transcripts in `.sequant/logs/relay/`) and clears the runtime files.
+ *
+ * Both operations swallow errors when relay is disabled or filesystem is
+ * read-only — relay must never block the underlying `sequant run` flow.
+ */
+import type { StateManager } from "../workflow/state-manager.js";
+export interface ActivationOptions {
+    /** Worktree path; falls back to `cwd` for spec-phase / main-repo relay. */
+    worktreePath?: string;
+    /** Main repo cwd (used for the PID file location). */
+    cwd?: string;
+    /** Optional state manager — updates IssueState.relay when provided. */
+    stateManager?: StateManager | null;
+    /** PID to record (defaults to current process). */
+    pid?: number;
+}
+export interface ActivationResult {
+    /** Was activation successful? */
+    activated: boolean;
+    /** Absolute path to the relay directory. */
+    relayDir: string;
+    /** Absolute path to the PID file. */
+    pidPath: string | null;
+    /** When activation occurred (ISO 8601). */
+    startedAt: string;
+    /** Error, if activation partially failed. Relay still considered active. */
+    warning: string | null;
+}
+/**
+ * Resolve the absolute path of `templates/relay/frame.txt` inside the
+ * installed sequant package. Used by phase-executor to set the
+ * SEQUANT_RELAY_FRAME env var so the bash hook can locate the template.
+ */
+export declare function resolveBundledFramePath(): string | null;
+/**
+ * Activate the relay for `issue`. Creates `<worktree>/.sequant/relay/`,
+ * writes `.sequant/pids/<issue>.pid` and (optionally) updates state.
+ */
+export declare function activateRelay(issue: number, options?: ActivationOptions): Promise<ActivationResult>;
+export interface DeactivationOptions extends ActivationOptions {
+    /** Phase whose work just ended — encoded in the archive dir name. */
+    phase: string;
+    /** When the relay was activated (echoed into archive meta.json). */
+    startedAt: string;
+}
+export interface DeactivationResult {
+    archived: boolean;
+    archivePath: string | null;
+    warning: string | null;
+}
+/**
+ * Deactivate the relay for `issue`: archive inbox/outbox, remove the pidfile,
+ * and clear IssueState.relay. Always returns — never throws.
+ */
+export declare function deactivateRelay(issue: number, options: DeactivationOptions): Promise<DeactivationResult>;

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

@@ -0,0 +1,122 @@
+/**
+ * Relay activation and deactivation lifecycle (#383).
+ *
+ * Activation creates the relay dir, writes the per-issue PID file, and updates
+ * IssueState.relay. Deactivation archives the relay dir (preserving inbox /
+ * outbox transcripts in `.sequant/logs/relay/`) and clears the runtime files.
+ *
+ * Both operations swallow errors when relay is disabled or filesystem is
+ * read-only — relay must never block the underlying `sequant run` flow.
+ */
+import { existsSync, mkdirSync } from "fs";
+import { fileURLToPath } from "url";
+import { dirname, resolve } from "path";
+import { archiveRelayDir, tallyMessageCount } from "./archive.js";
+import { relayDirFor } from "./paths.js";
+import { writePidFile, removePidFile } from "./pid.js";
+/**
+ * Resolve the absolute path of `templates/relay/frame.txt` inside the
+ * installed sequant package. Used by phase-executor to set the
+ * SEQUANT_RELAY_FRAME env var so the bash hook can locate the template.
+ */
+export function resolveBundledFramePath() {
+    const __dirname = dirname(fileURLToPath(import.meta.url));
+    let dir = __dirname;
+    for (let i = 0; i < 6; i++) {
+        const candidate = resolve(dir, "templates", "relay", "frame.txt");
+        if (existsSync(candidate))
+            return candidate;
+        dir = dirname(dir);
+    }
+    return null;
+}
+/**
+ * Activate the relay for `issue`. Creates `<worktree>/.sequant/relay/`,
+ * writes `.sequant/pids/<issue>.pid` and (optionally) updates state.
+ */
+export async function activateRelay(issue, options = {}) {
+    const startedAt = new Date().toISOString();
+    const pid = options.pid ?? process.pid;
+    const relayDir = relayDirFor(issue, {
+        worktreePath: options.worktreePath,
+        cwd: options.cwd,
+    });
+    let warning = null;
+    try {
+        mkdirSync(relayDir, { recursive: true });
+    }
+    catch (err) {
+        warning = `Failed to create relay dir: ${err instanceof Error ? err.message : String(err)}`;
+    }
+    let pidPath = null;
+    try {
+        pidPath = writePidFile(issue, pid, options.cwd ?? process.cwd());
+    }
+    catch (err) {
+        warning =
+            (warning ? warning + "; " : "") +
+                `Failed to write pid file: ${err instanceof Error ? err.message : String(err)}`;
+    }
+    if (options.stateManager) {
+        try {
+            await options.stateManager.setRelayState(issue, {
+                enabled: true,
+                pid,
+                startedAt,
+                messageCount: 0,
+            });
+        }
+        catch {
+            // Issue may not be in state yet (race with initializeIssue) — non-fatal.
+        }
+    }
+    return {
+        activated: warning === null,
+        relayDir,
+        pidPath,
+        startedAt,
+        warning,
+    };
+}
+/**
+ * Deactivate the relay for `issue`: archive inbox/outbox, remove the pidfile,
+ * and clear IssueState.relay. Always returns — never throws.
+ */
+export async function deactivateRelay(issue, options) {
+    let warning = null;
+    const cwd = options.cwd ?? process.cwd();
+    const messageCount = tallyMessageCount(issue, {
+        worktreePath: options.worktreePath,
+        cwd,
+    });
+    const archive = archiveRelayDir(issue, {
+        phase: options.phase,
+        startedAt: options.startedAt,
+        messageCount,
+        worktreePath: options.worktreePath,
+        cwd,
+        archiveCwd: cwd,
+    });
+    if (archive.error) {
+        warning = archive.error;
+    }
+    try {
+        removePidFile(issue, cwd);
+    }
+    catch {
+        /* swallow */
+    }
+    if (options.stateManager) {
+        try {
+            await options.stateManager.setRelayState(issue, null);
+        }
+        catch {
+            /* swallow */
+        }
+    }
+    return {
+        archived: archive.archived,
+        archivePath: archive.archivePath,
+        warning,
+    };
+}

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

@@ -0,0 +1,34 @@
+/**
+ * Archive the working relay directory to `.sequant/logs/relay/<issue>-<phase>-<ts>/`
+ * at phase end so transcripts survive worktree teardown (AC-6, AC-D2, AC-D4).
+ *
+ * The archive copies inbox.jsonl + outbox.jsonl + meta.json, then clears the
+ * working dir. Failures are non-fatal — teardown must still proceed.
+ */
+import { type RelayPathOptions } from "./paths.js";
+export interface ArchiveOptions extends RelayPathOptions {
+    /** Phase whose work just finished — used in the archive dir name. */
+    phase: string;
+    /** When the relay was activated. */
+    startedAt: string;
+    /** Total messages exchanged during the run. */
+    messageCount: number;
+    /** Override timestamp (test seam). */
+    endedAt?: string;
+    /** Main repo cwd for archive root (`.sequant/logs/relay/`). */
+    archiveCwd?: string;
+}
+export interface ArchiveResult {
+    archived: boolean;
+    archivePath: string | null;
+    error: string | null;
+}
+/**
+ * Archive the relay directory for `issue` and clear it. Idempotent; if the
+ * dir doesn't exist, returns `{ archived: false }` without error.
+ */
+export declare function archiveRelayDir(issue: number, options: ArchiveOptions): ArchiveResult;
+/** Count messages currently in the inbox + outbox of a relay dir. */
+export declare function tallyMessageCount(issue: number, options?: RelayPathOptions): number;
+/** List archived relay directories for an issue (sorted newest first). */
+export declare function listArchives(issue: number, archiveCwd?: string): string[];

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

@@ -0,0 +1,106 @@
+/**
+ * Archive the working relay directory to `.sequant/logs/relay/<issue>-<phase>-<ts>/`
+ * at phase end so transcripts survive worktree teardown (AC-6, AC-D2, AC-D4).
+ *
+ * The archive copies inbox.jsonl + outbox.jsonl + meta.json, then clears the
+ * working dir. Failures are non-fatal — teardown must still proceed.
+ */
+import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync, } from "fs";
+import { join } from "path";
+import { archiveDirFor, relayDirFor, RELAY_CURSOR, RELAY_INBOX, RELAY_OUTBOX, } from "./paths.js";
+import { RelayArchiveMetaSchema } from "./types.js";
+function countLines(path) {
+    if (!existsSync(path))
+        return 0;
+    try {
+        const st = statSync(path);
+        if (st.size === 0)
+            return 0;
+        const text = readFileSync(path, "utf-8");
+        return text.split("\n").filter((l) => l.trim() !== "").length;
+    }
+    catch {
+        return 0;
+    }
+}
+/**
+ * Archive the relay directory for `issue` and clear it. Idempotent; if the
+ * dir doesn't exist, returns `{ archived: false }` without error.
+ */
+export function archiveRelayDir(issue, options) {
+    const srcDir = relayDirFor(issue, options);
+    if (!existsSync(srcDir)) {
+        return { archived: false, archivePath: null, error: null };
+    }
+    // Idempotent: if there are no transcripts to preserve, skip creating an
+    // empty archive dir. Lets callers safely deactivate twice.
+    const hasInbox = existsSync(join(srcDir, RELAY_INBOX));
+    const hasOutbox = existsSync(join(srcDir, RELAY_OUTBOX));
+    if (!hasInbox && !hasOutbox) {
+        return { archived: false, archivePath: null, error: null };
+    }
+    const endedAt = options.endedAt ?? new Date().toISOString();
+    let destDir = archiveDirFor(issue, options.phase, endedAt, options.archiveCwd ?? process.cwd());
+    // If the dest exists (clock collision on same-second), append a suffix.
+    if (existsSync(destDir)) {
+        let n = 2;
+        while (existsSync(`${destDir}.${n}`))
+            n++;
+        destDir = `${destDir}.${n}`;
+    }
+    try {
+        mkdirSync(destDir, { recursive: true });
+        // Copy inbox/outbox if present.
+        for (const name of [RELAY_INBOX, RELAY_OUTBOX]) {
+            const src = join(srcDir, name);
+            if (existsSync(src)) {
+                copyFileSync(src, join(destDir, name));
+            }
+        }
+        // Write meta.json.
+        const meta = RelayArchiveMetaSchema.parse({
+            issue,
+            phase: options.phase,
+            startedAt: options.startedAt,
+            endedAt,
+            messageCount: options.messageCount,
+        });
+        writeFileSync(join(destDir, "meta.json"), JSON.stringify(meta, null, 2), "utf-8");
+        // Clear the working relay dir (inbox/outbox/cursor).
+        for (const name of [RELAY_INBOX, RELAY_OUTBOX, RELAY_CURSOR]) {
+            const p = join(srcDir, name);
+            if (existsSync(p))
+                rmSync(p, { force: true });
+        }
+        return { archived: true, archivePath: destDir, error: null };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { archived: false, archivePath: null, error: message };
+    }
+}
+/** Count messages currently in the inbox + outbox of a relay dir. */
+export function tallyMessageCount(issue, options = {}) {
+    const dir = relayDirFor(issue, options);
+    if (!existsSync(dir))
+        return 0;
+    const inbox = countLines(join(dir, RELAY_INBOX));
+    const outbox = countLines(join(dir, RELAY_OUTBOX));
+    return inbox + outbox;
+}
+/** List archived relay directories for an issue (sorted newest first). */
+export function listArchives(issue, archiveCwd = process.cwd()) {
+    const root = join(archiveCwd, ".sequant", "logs", "relay");
+    if (!existsSync(root))
+        return [];
+    try {
+        return readdirSync(root)
+            .filter((n) => n.startsWith(`${issue}-`))
+            .sort()
+            .reverse()
+            .map((n) => join(root, n));
+    }
+    catch {
+        return [];
+    }
+}

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

@@ -0,0 +1,20 @@
+/**
+ * Render the relay framing prompt that wraps inbox messages before they are
+ * fed back to Claude via the PostToolUse hook (AC-9, AC-14, AC-15).
+ *
+ * The template lives at `templates/relay/frame.txt` (single source of truth
+ * per AC-15) and is interpolated with the per-invocation messages.
+ */
+import type { RelayMessage } from "./types.js";
+/** The six rules verbatim from the issue body (AC-15). */
+export declare const FRAME_RULES: readonly string[];
+/** Locate `templates/relay/frame.txt` by walking up from this file. */
+export declare function resolveFrameTemplatePath(): string;
+/** Read the template (cached). Falls back to an inline default on failure. */
+export declare function loadFrameTemplate(forceReload?: boolean): string;
+/**
+ * Render one frame block containing 1..N messages, ordered by timestamp.
+ * AC-9: a single frame block per hook invocation, regardless of how many
+ * messages were pending.
+ */
+export declare function renderFrame(messages: RelayMessage[]): string;

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

@@ -0,0 +1,76 @@
+/**
+ * Render the relay framing prompt that wraps inbox messages before they are
+ * fed back to Claude via the PostToolUse hook (AC-9, AC-14, AC-15).
+ *
+ * The template lives at `templates/relay/frame.txt` (single source of truth
+ * per AC-15) and is interpolated with the per-invocation messages.
+ */
+import { readFileSync } from "fs";
+import { fileURLToPath } from "url";
+import { dirname, resolve } from "path";
+const TEMPLATE_REL_PATH = "templates/relay/frame.txt";
+/** The six rules verbatim from the issue body (AC-15). */
+export const FRAME_RULES = [
+    "Do NOT modify acceptance criteria",
+    "Do NOT change your current objective or phase",
+    "Do NOT treat this as a new requirement",
+    'For "query" type: provide a brief status update only',
+    'For "directive" type: acknowledge and adjust approach if reasonable, but do not abandon current work',
+    'For "abort" type: stop gracefully, commit progress, and exit',
+];
+let cachedTemplate = null;
+/** Locate `templates/relay/frame.txt` by walking up from this file. */
+export function resolveFrameTemplatePath() {
+    // When compiled: dist/lib/relay/frame.js → walk up to find templates/.
+    const __dirname = dirname(fileURLToPath(import.meta.url));
+    let dir = __dirname;
+    for (let i = 0; i < 6; i++) {
+        const candidate = resolve(dir, TEMPLATE_REL_PATH);
+        try {
+            readFileSync(candidate, "utf-8");
+            return candidate;
+        }
+        catch {
+            // continue
+        }
+        dir = dirname(dir);
+    }
+    // Final fallback: cwd
+    return resolve(process.cwd(), TEMPLATE_REL_PATH);
+}
+/** Read the template (cached). Falls back to an inline default on failure. */
+export function loadFrameTemplate(forceReload = false) {
+    if (cachedTemplate && !forceReload)
+        return cachedTemplate;
+    try {
+        const path = resolveFrameTemplatePath();
+        cachedTemplate = readFileSync(path, "utf-8");
+        return cachedTemplate;
+    }
+    catch {
+        // Fallback that still contains the six rules verbatim.
+        cachedTemplate =
+            "[SEQUANT RELAY — message from user]\n" +
+                "Respond briefly in .sequant/relay/outbox.jsonl, then continue your current task unchanged.\n" +
+                "Rules:\n" +
+                FRAME_RULES.map((r) => `- ${r}`).join("\n") +
+                "\n\n{{MESSAGES}}\n";
+        return cachedTemplate;
+    }
+}
+function formatSingleMessage(m) {
+    const body = m.type === "abort" && !m.message ? "" : (m.message ?? "");
+    return `Type: ${m.type}\nMessage: ${JSON.stringify(body)}`;
+}
+/**
+ * Render one frame block containing 1..N messages, ordered by timestamp.
+ * AC-9: a single frame block per hook invocation, regardless of how many
+ * messages were pending.
+ */
+export function renderFrame(messages) {
+    if (messages.length === 0)
+        return "";
+    const sorted = [...messages].sort((a, b) => a.timestamp.localeCompare(b.timestamp));
+    const block = sorted.map(formatSingleMessage).join("\n---\n");
+    return loadFrameTemplate().replace("{{MESSAGES}}", block);
+}

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

@@ -0,0 +1,13 @@
+/**
+ * Interactive relay (#383): file-based IPC between the user terminal and a
+ * headless `sequant run` session. See `src/lib/relay/types.ts` for the wire
+ * format and `templates/relay/frame.txt` for the framing prompt.
+ */
+export * from "./types.js";
+export * from "./paths.js";
+export * from "./writer.js";
+export * from "./reader.js";
+export * from "./frame.js";
+export * from "./pid.js";
+export * from "./archive.js";
+export * from "./activation.js";

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

@@ -0,0 +1,13 @@
+/**
+ * Interactive relay (#383): file-based IPC between the user terminal and a
+ * headless `sequant run` session. See `src/lib/relay/types.ts` for the wire
+ * format and `templates/relay/frame.txt` for the framing prompt.
+ */
+export * from "./types.js";
+export * from "./paths.js";
+export * from "./writer.js";
+export * from "./reader.js";
+export * from "./frame.js";
+export * from "./pid.js";
+export * from "./archive.js";
+export * from "./activation.js";

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

@@ -0,0 +1,43 @@
+/**
+ * Path resolution for relay directories.
+ *
+ * The relay lives inside a per-issue worktree at `<worktree>/.sequant/relay/`.
+ * During the `spec` phase the worktree doesn't exist yet, so we fall back to
+ * the main repo at `.sequant/relay/<issue>/`. The phase-executor sets
+ * `SEQUANT_WORKTREE` whenever an isolated worktree is active.
+ */
+export declare const RELAY_INBOX = "inbox.jsonl";
+export declare const RELAY_OUTBOX = "outbox.jsonl";
+export declare const RELAY_CURSOR = ".cursor";
+export declare const RELAY_PIDS_DIR = ".sequant/pids";
+export interface RelayPathOptions {
+    /** Optional override; if omitted, reads SEQUANT_WORKTREE then falls back. */
+    worktreePath?: string;
+    /** Optional override for the main repo cwd (test seam). */
+    cwd?: string;
+}
+/**
+ * Resolve the absolute relay directory for an issue.
+ *
+ * - With a worktree: `<worktree>/.sequant/relay/`
+ * - Without (spec phase or CLI from main repo): `<cwd>/.sequant/relay/<issue>/`
+ */
+export declare function relayDirFor(issue: number, options?: RelayPathOptions): string;
+/** Path to the inbox JSONL file. */
+export declare function inboxPathFor(issue: number, options?: RelayPathOptions): string;
+/** Path to the outbox JSONL file. */
+export declare function outboxPathFor(issue: number, options?: RelayPathOptions): string;
+/** Path to the reader cursor file. */
+export declare function cursorPathFor(issue: number, options?: RelayPathOptions): string;
+/** Path to the per-issue PID file. */
+export declare function pidPathFor(issue: number, cwd?: string): string;
+/**
+ * Resolve the archive root directory for the relay logs:
+ * `<cwd>/.sequant/logs/relay/`.
+ */
+export declare function archiveRootDir(cwd?: string): string;
+/**
+ * Resolve the archive directory for a particular phase end:
+ * `<archiveRoot>/<issue>-<phase>-<timestamp>/`.
+ */
+export declare function archiveDirFor(issue: number, phase: string, timestamp: string, cwd?: string): string;

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

@@ -0,0 +1,59 @@
+/**
+ * Path resolution for relay directories.
+ *
+ * The relay lives inside a per-issue worktree at `<worktree>/.sequant/relay/`.
+ * During the `spec` phase the worktree doesn't exist yet, so we fall back to
+ * the main repo at `.sequant/relay/<issue>/`. The phase-executor sets
+ * `SEQUANT_WORKTREE` whenever an isolated worktree is active.
+ */
+import { join, resolve } from "path";
+export const RELAY_INBOX = "inbox.jsonl";
+export const RELAY_OUTBOX = "outbox.jsonl";
+export const RELAY_CURSOR = ".cursor";
+export const RELAY_PIDS_DIR = ".sequant/pids";
+/**
+ * Resolve the absolute relay directory for an issue.
+ *
+ * - With a worktree: `<worktree>/.sequant/relay/`
+ * - Without (spec phase or CLI from main repo): `<cwd>/.sequant/relay/<issue>/`
+ */
+export function relayDirFor(issue, options = {}) {
+    const worktree = options.worktreePath ?? process.env.SEQUANT_WORKTREE;
+    const cwd = options.cwd ?? process.cwd();
+    if (worktree && worktree.trim() !== "") {
+        return resolve(worktree, ".sequant", "relay");
+    }
+    return resolve(cwd, ".sequant", "relay", String(issue));
+}
+/** Path to the inbox JSONL file. */
+export function inboxPathFor(issue, options = {}) {
+    return join(relayDirFor(issue, options), RELAY_INBOX);
+}
+/** Path to the outbox JSONL file. */
+export function outboxPathFor(issue, options = {}) {
+    return join(relayDirFor(issue, options), RELAY_OUTBOX);
+}
+/** Path to the reader cursor file. */
+export function cursorPathFor(issue, options = {}) {
+    return join(relayDirFor(issue, options), RELAY_CURSOR);
+}
+/** Path to the per-issue PID file. */
+export function pidPathFor(issue, cwd = process.cwd()) {
+    return resolve(cwd, RELAY_PIDS_DIR, `${issue}.pid`);
+}
+/**
+ * Resolve the archive root directory for the relay logs:
+ * `<cwd>/.sequant/logs/relay/`.
+ */
+export function archiveRootDir(cwd = process.cwd()) {
+    return resolve(cwd, ".sequant", "logs", "relay");
+}
+/**
+ * Resolve the archive directory for a particular phase end:
+ * `<archiveRoot>/<issue>-<phase>-<timestamp>/`.
+ */
+export function archiveDirFor(issue, phase, timestamp, cwd = process.cwd()) {
+    // Sanitize timestamp for filesystem use (colons are illegal on Windows).
+    const safeTs = timestamp.replace(/[:.]/g, "-");
+    return join(archiveRootDir(cwd), `${issue}-${phase}-${safeTs}`);
+}