@indigoai-us/hq-cli 5.256.0 → 5.257.0

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## [Unreleased]
 
+## [5.257.0] — 2026-09-28
+
+### Added
+
+- Add `hq lanes hold` to record company-scoped repository merge holds and
+  refuse recognized merge commands while the `lanes.repo-merge-hold` gate is
+  enabled. Hold history and release reasons stay in the local record. Checks
+  fail open with a named error when they cannot parse a command or read a hold,
+  and recognize pull-request URLs plus assignment, `env`, and `timeout` forms.
+
 ## [5.256.0] — 2026-09-28
 
 ## [5.255.0] — 2026-09-28

package/dist/command-catalog.generated.d.ts

@@ -7375,6 +7375,102 @@ export declare const COMMAND_CATALOG: readonly [{
             readonly description: "Emit JSON instead of the team page text";
         }];
         readonly subcommands: readonly [];
+    }, {
+        readonly name: "hold";
+        readonly description: "Set and enforce repository merge holds";
+        readonly aliases: readonly [];
+        readonly hidden: false;
+        readonly usage: "[options] [command]";
+        readonly arguments: readonly [];
+        readonly options: readonly [];
+        readonly subcommands: readonly [{
+            readonly name: "set";
+            readonly description: "Set or replace a repository merge hold";
+            readonly aliases: readonly [];
+            readonly hidden: false;
+            readonly usage: "[options] <repo>";
+            readonly arguments: readonly [{
+                readonly name: "repo";
+                readonly required: true;
+                readonly variadic: false;
+            }];
+            readonly options: readonly [{
+                readonly flags: "--company <slug>";
+                readonly description: "Company that owns this repository hold";
+            }, {
+                readonly flags: "--reason <text>";
+                readonly description: "Why merges are held";
+            }, {
+                readonly flags: "--until <time>";
+                readonly description: "Expiry as an ISO timestamp or duration such as 4h";
+            }, {
+                readonly flags: "--json";
+                readonly description: "JSON on stdout (always)";
+            }];
+            readonly subcommands: readonly [];
+        }, {
+            readonly name: "list";
+            readonly description: "List active and expired repository merge holds";
+            readonly aliases: readonly [];
+            readonly hidden: false;
+            readonly usage: "[options]";
+            readonly arguments: readonly [];
+            readonly options: readonly [{
+                readonly flags: "--json";
+                readonly description: "Print JSON";
+            }];
+            readonly subcommands: readonly [];
+        }, {
+            readonly name: "show";
+            readonly description: "Show a repository merge hold";
+            readonly aliases: readonly [];
+            readonly hidden: false;
+            readonly usage: "[options] <repo>";
+            readonly arguments: readonly [{
+                readonly name: "repo";
+                readonly required: true;
+                readonly variadic: false;
+            }];
+            readonly options: readonly [{
+                readonly flags: "--json";
+                readonly description: "JSON on stdout (always)";
+            }];
+            readonly subcommands: readonly [];
+        }, {
+            readonly name: "release";
+            readonly description: "Release an existing repository merge hold";
+            readonly aliases: readonly [];
+            readonly hidden: false;
+            readonly usage: "[options] <repo>";
+            readonly arguments: readonly [{
+                readonly name: "repo";
+                readonly required: true;
+                readonly variadic: false;
+            }];
+            readonly options: readonly [{
+                readonly flags: "--reason <text>";
+                readonly description: "Why the hold is being released";
+            }, {
+                readonly flags: "--json";
+                readonly description: "JSON on stdout (always)";
+            }];
+            readonly subcommands: readonly [];
+        }, {
+            readonly name: "check";
+            readonly description: "Refuse merge commands targeting an actively held repository";
+            readonly aliases: readonly [];
+            readonly hidden: false;
+            readonly usage: "[options]";
+            readonly arguments: readonly [];
+            readonly options: readonly [{
+                readonly flags: "--command <shell-command>";
+                readonly description: "Command to inspect without executing it";
+            }, {
+                readonly flags: "--json";
+                readonly description: "Print JSON";
+            }];
+            readonly subcommands: readonly [];
+        }];
     }, {
         readonly name: "outpost-pruner";
         readonly description: "Inspect, install, and run safe outpost worktree pruning";

package/dist/command-catalog.generated.js

@@ -9534,6 +9534,130 @@ export const COMMAND_CATALOG = [
                 ],
                 "subcommands": []
             },
+            {
+                "name": "hold",
+                "description": "Set and enforce repository merge holds",
+                "aliases": [],
+                "hidden": false,
+                "usage": "[options] [command]",
+                "arguments": [],
+                "options": [],
+                "subcommands": [
+                    {
+                        "name": "set",
+                        "description": "Set or replace a repository merge hold",
+                        "aliases": [],
+                        "hidden": false,
+                        "usage": "[options] <repo>",
+                        "arguments": [
+                            {
+                                "name": "repo",
+                                "required": true,
+                                "variadic": false
+                            }
+                        ],
+                        "options": [
+                            {
+                                "flags": "--company <slug>",
+                                "description": "Company that owns this repository hold"
+                            },
+                            {
+                                "flags": "--reason <text>",
+                                "description": "Why merges are held"
+                            },
+                            {
+                                "flags": "--until <time>",
+                                "description": "Expiry as an ISO timestamp or duration such as 4h"
+                            },
+                            {
+                                "flags": "--json",
+                                "description": "JSON on stdout (always)"
+                            }
+                        ],
+                        "subcommands": []
+                    },
+                    {
+                        "name": "list",
+                        "description": "List active and expired repository merge holds",
+                        "aliases": [],
+                        "hidden": false,
+                        "usage": "[options]",
+                        "arguments": [],
+                        "options": [
+                            {
+                                "flags": "--json",
+                                "description": "Print JSON"
+                            }
+                        ],
+                        "subcommands": []
+                    },
+                    {
+                        "name": "show",
+                        "description": "Show a repository merge hold",
+                        "aliases": [],
+                        "hidden": false,
+                        "usage": "[options] <repo>",
+                        "arguments": [
+                            {
+                                "name": "repo",
+                                "required": true,
+                                "variadic": false
+                            }
+                        ],
+                        "options": [
+                            {
+                                "flags": "--json",
+                                "description": "JSON on stdout (always)"
+                            }
+                        ],
+                        "subcommands": []
+                    },
+                    {
+                        "name": "release",
+                        "description": "Release an existing repository merge hold",
+                        "aliases": [],
+                        "hidden": false,
+                        "usage": "[options] <repo>",
+                        "arguments": [
+                            {
+                                "name": "repo",
+                                "required": true,
+                                "variadic": false
+                            }
+                        ],
+                        "options": [
+                            {
+                                "flags": "--reason <text>",
+                                "description": "Why the hold is being released"
+                            },
+                            {
+                                "flags": "--json",
+                                "description": "JSON on stdout (always)"
+                            }
+                        ],
+                        "subcommands": []
+                    },
+                    {
+                        "name": "check",
+                        "description": "Refuse merge commands targeting an actively held repository",
+                        "aliases": [],
+                        "hidden": false,
+                        "usage": "[options]",
+                        "arguments": [],
+                        "options": [
+                            {
+                                "flags": "--command <shell-command>",
+                                "description": "Command to inspect without executing it"
+                            },
+                            {
+                                "flags": "--json",
+                                "description": "Print JSON"
+                            }
+                        ],
+                        "subcommands": []
+                    }
+                ]
+            },
             {
                 "name": "outpost-pruner",
                 "description": "Inspect, install, and run safe outpost worktree pruning",

package/dist/commands/lanes-hold.d.ts

@@ -0,0 +1,41 @@
+import type { Command } from "commander";
+import type { LaneCompanyRef } from "../lib/lanes/types.js";
+export declare const LANES_REPO_MERGE_HOLD_FLAG = "lanes.repo-merge-hold";
+export declare const REPO_MERGE_HOLDS_REL: string;
+declare const HOLD_SCHEMA_VERSION = "hq-lanes-repo-merge-hold.v1";
+interface HoldHistoryEntry {
+    set_at: string;
+    until: string;
+    reason: string;
+    set_by_lane: string | null;
+    set_by_session: string | null;
+    released_at?: string;
+    released_reason?: string;
+}
+export interface RepoMergeHold {
+    schema_version: typeof HOLD_SCHEMA_VERSION;
+    repo: string;
+    company: LaneCompanyRef;
+    reason: string;
+    set_at: string;
+    until: string;
+    set_by_lane: string | null;
+    set_by_session: string | null;
+    released_at?: string;
+    released_reason?: string;
+    history: HoldHistoryEntry[];
+}
+export interface LaneRepoMergeHoldDeps {
+    hqRoot: () => string;
+    resolveCompany: (company?: string) => Promise<LaneCompanyRef>;
+    now: () => Date;
+    env: NodeJS.ProcessEnv;
+    mergeHoldEnabled?: (company: LaneCompanyRef) => boolean | Promise<boolean>;
+}
+type WrapHandler = <Args extends unknown[]>(action: (...args: Args) => Promise<void>) => (...args: Args) => Promise<void>;
+export declare function repoMergeHoldPath(hqRoot: string, repo: string): string;
+/** Serialize the read-modify-write cycle so concurrent set/release calls cannot overwrite each other. */
+export declare function withRepoMergeHoldRecordLock<T>(recordPath: string, action: () => T | Promise<T>): Promise<T>;
+export declare function registerLaneRepoMergeHoldCommand(lanes: Command, deps: LaneRepoMergeHoldDeps, wrap: WrapHandler): void;
+export {};
+//# sourceMappingURL=lanes-hold.d.ts.map

package/dist/commands/lanes-hold.js

@@ -0,0 +1,805 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { LanesError } from "../lib/lanes/errors.js";
+import { listLaneIds, readLane } from "../lib/lanes/store.js";
+import { appendDropboxMessage } from "../lib/lanes/dropbox.js";
+import { assertNoSecretText } from "../lib/lanes/text-scan.js";
+import { readLanesFlagLocalOverride, readLanesRegistryFlag } from "../lib/lanes/registry-flag.js";
+import { sessionIdFromEnv } from "../lib/mesh/live/session-identity.js";
+export const LANES_REPO_MERGE_HOLD_FLAG = "lanes.repo-merge-hold";
+export const REPO_MERGE_HOLDS_REL = path.join("workspace", "lanes", "holds");
+const HOLD_SCHEMA_VERSION = "hq-lanes-repo-merge-hold.v1";
+const HISTORY_CAP = 50;
+const HOLD_LOCK_WAIT_MS = 5_000;
+const HOLD_LOCK_STALE_MS = 5 * 60_000;
+function fail(error, message, details = {}) {
+    throw new LanesError(error, message, details);
+}
+function canonicalRepo(raw) {
+    const value = raw.trim();
+    const parts = value.split("/");
+    if (parts.length !== 2) {
+        return fail("repo_hold_repo_invalid", "Repository must be a safe owner/repo pair", { field: "repo" });
+    }
+    const [owner, repository] = parts;
+    if (!owner || !repository ||
+        !/^[A-Za-z0-9][A-Za-z0-9-]{0,38}$/.test(owner) ||
+        !/^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/.test(repository) ||
+        owner === "." || owner === ".." || repository === "." || repository === "..") {
+        return fail("repo_hold_repo_invalid", "Repository must be a safe owner/repo pair", { field: "repo" });
+    }
+    return `${owner.toLowerCase()}/${repository.toLowerCase()}`;
+}
+function holdFilePath(hqRoot, repo) {
+    const [owner, repository] = canonicalRepo(repo).split("/");
+    return path.join(hqRoot, REPO_MERGE_HOLDS_REL, `${owner}__${repository}.json`);
+}
+export function repoMergeHoldPath(hqRoot, repo) {
+    return holdFilePath(hqRoot, repo);
+}
+function nonEmptyText(field, raw) {
+    const value = raw.trim();
+    if (!value)
+        return fail("repo_hold_text_empty", `${field} must not be empty`, { field });
+    assertNoSecretText(field, value);
+    return value;
+}
+function parseUntil(raw, now) {
+    const value = raw.trim();
+    let timestamp;
+    const duration = /^(\d+)([smhd])$/i.exec(value);
+    if (duration) {
+        const amount = Number(duration[1]);
+        const unit = duration[2]?.toLowerCase();
+        const milliseconds = unit === "s" ? 1_000 : unit === "m" ? 60_000 : unit === "h" ? 3_600_000 : 86_400_000;
+        timestamp = now.getTime() + amount * milliseconds;
+    }
+    else {
+        const iso = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2})(?::(\d{2})(?:\.\d{1,3})?)?(Z|[+-]\d{2}:\d{2})$/.exec(value);
+        if (!iso) {
+            return fail("repo_hold_until_invalid", "Until must be an ISO timestamp or a duration such as 4h", { field: "until" });
+        }
+        const year = Number(iso[1]);
+        const month = Number(iso[2]);
+        const day = Number(iso[3]);
+        const hour = Number(iso[4]);
+        const minute = Number(iso[5]);
+        const second = Number(iso[6] ?? "0");
+        const daysInMonth = new Date(Date.UTC(year, month, 0)).getUTCDate();
+        if (month < 1 || month > 12 || day < 1 || day > daysInMonth ||
+            hour > 23 || minute > 59 || second > 59) {
+            return fail("repo_hold_until_invalid", "Until must be a valid ISO timestamp", { field: "until" });
+        }
+        timestamp = Date.parse(value);
+    }
+    if (!Number.isFinite(timestamp)) {
+        return fail("repo_hold_until_invalid", "Until must be an ISO timestamp or a duration such as 4h", { field: "until" });
+    }
+    if (timestamp <= now.getTime()) {
+        return fail("repo_hold_until_past", "Hold expiry must be in the future", { field: "until" });
+    }
+    return new Date(timestamp).toISOString();
+}
+function isObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function isCanonicalTimestamp(value) {
+    if (typeof value !== "string")
+        return false;
+    const timestamp = Date.parse(value);
+    return Number.isFinite(timestamp) && new Date(timestamp).toISOString() === value;
+}
+function parseHold(raw, file) {
+    if (!isObject(raw))
+        return fail("repo_hold_invalid", "Merge hold record must be an object", { path: file });
+    const company = raw.company;
+    const history = raw.history;
+    if (raw.schema_version !== HOLD_SCHEMA_VERSION || typeof raw.repo !== "string" ||
+        !isObject(company) || typeof company.slug !== "string" || !company.slug.trim() ||
+        typeof company.uid !== "string" || !company.uid.trim() ||
+        typeof raw.reason !== "string" || !raw.reason.trim() ||
+        !isCanonicalTimestamp(raw.set_at) || !isCanonicalTimestamp(raw.until) ||
+        !(raw.set_by_lane === null || typeof raw.set_by_lane === "string") ||
+        !(raw.set_by_session === null || typeof raw.set_by_session === "string") ||
+        !Array.isArray(history) || history.length > HISTORY_CAP ||
+        (raw.released_at !== undefined && !isCanonicalTimestamp(raw.released_at)) ||
+        (raw.released_reason !== undefined && typeof raw.released_reason !== "string")) {
+        return fail("repo_hold_invalid", "Merge hold record has invalid fields", { path: file });
+    }
+    let repo;
+    try {
+        repo = canonicalRepo(raw.repo);
+    }
+    catch {
+        return fail("repo_hold_invalid", "Merge hold record has an invalid repository", { path: file });
+    }
+    if (repo !== raw.repo)
+        return fail("repo_hold_invalid", "Merge hold repository is not canonical", { path: file });
+    if ((raw.released_at === undefined) !== (raw.released_reason === undefined)) {
+        return fail("repo_hold_invalid", "Released merge hold must include both release fields", { path: file });
+    }
+    if (raw.released_at !== undefined && (!raw.released_reason || !raw.released_reason.trim())) {
+        return fail("repo_hold_invalid", "Released merge hold is missing its reason", { path: file });
+    }
+    assertNoSecretText("hold.reason", raw.reason);
+    if (typeof raw.released_reason === "string")
+        assertNoSecretText("hold.released_reason", raw.released_reason);
+    for (const entry of history) {
+        if (!isObject(entry) || !isCanonicalTimestamp(entry.set_at) || !isCanonicalTimestamp(entry.until) ||
+            typeof entry.reason !== "string" || !entry.reason.trim() ||
+            !(entry.set_by_lane === null || typeof entry.set_by_lane === "string") ||
+            !(entry.set_by_session === null || typeof entry.set_by_session === "string") ||
+            (entry.released_at !== undefined && !isCanonicalTimestamp(entry.released_at)) ||
+            (entry.released_reason !== undefined && typeof entry.released_reason !== "string")) {
+            return fail("repo_hold_invalid", "Merge hold history has invalid entries", { path: file });
+        }
+        if ((entry.released_at === undefined) !== (entry.released_reason === undefined)) {
+            return fail("repo_hold_invalid", "Merge hold history release fields are incomplete", { path: file });
+        }
+        if (entry.released_reason !== undefined && !entry.released_reason.trim()) {
+            return fail("repo_hold_invalid", "Merge hold history release reason is empty", { path: file });
+        }
+        assertNoSecretText("hold.history.reason", entry.reason);
+        if (typeof entry.released_reason === "string")
+            assertNoSecretText("hold.history.released_reason", entry.released_reason);
+    }
+    return raw;
+}
+function readHold(hqRoot, repo) {
+    const file = holdFilePath(hqRoot, repo);
+    let contents;
+    try {
+        contents = fs.readFileSync(file, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        return fail("repo_hold_unreadable", "Merge hold record could not be read", { path: file });
+    }
+    let raw;
+    try {
+        raw = JSON.parse(contents);
+    }
+    catch {
+        return fail("repo_hold_invalid", "Merge hold record is not valid JSON", { path: file });
+    }
+    const hold = parseHold(raw, file);
+    if (holdFilePath(hqRoot, hold.repo) !== file) {
+        return fail("repo_hold_invalid", "Merge hold filename does not match its repository", { path: file });
+    }
+    return hold;
+}
+function listHolds(hqRoot) {
+    const directory = path.join(hqRoot, REPO_MERGE_HOLDS_REL);
+    let names;
+    try {
+        names = fs.readdirSync(directory).filter((name) => name.endsWith(".json")).sort();
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return [];
+        return fail("repo_hold_unreadable", "Merge hold directory could not be read", { path: directory });
+    }
+    return names.map((name) => {
+        const file = path.join(directory, name);
+        let raw;
+        try {
+            raw = JSON.parse(fs.readFileSync(file, "utf8"));
+        }
+        catch {
+            return fail("repo_hold_invalid", "Merge hold record could not be parsed", { path: file });
+        }
+        const hold = parseHold(raw, file);
+        if (holdFilePath(hqRoot, hold.repo) !== file) {
+            return fail("repo_hold_invalid", "Merge hold filename does not match its repository", { path: file });
+        }
+        return hold;
+    });
+}
+function writeHold(hqRoot, hold) {
+    const file = holdFilePath(hqRoot, hold.repo);
+    const directory = path.dirname(file);
+    fs.mkdirSync(directory, { recursive: true });
+    const temp = `${file}.${process.pid}.${Date.now()}.tmp`;
+    try {
+        fs.writeFileSync(temp, `${JSON.stringify(hold, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+        fs.renameSync(temp, file);
+    }
+    catch (error) {
+        try {
+            fs.rmSync(temp, { force: true });
+        }
+        catch (cleanupError) {
+            process.stderr.write(`hq lanes hold: temporary hold cleanup failed: ${cleanupError instanceof Error ? cleanupError.message : String(cleanupError)}\n`);
+        }
+        throw error;
+    }
+}
+function holdLockOwnerAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code !== "ESRCH";
+    }
+}
+function removeStaleHoldLock(lockPath) {
+    let first;
+    try {
+        first = fs.lstatSync(lockPath);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return true;
+        throw error;
+    }
+    if (Date.now() - first.mtimeMs < HOLD_LOCK_STALE_MS)
+        return false;
+    let pid;
+    try {
+        pid = Number(fs.readFileSync(lockPath, "utf8").split("\n", 1)[0]);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return true;
+        throw error;
+    }
+    if (!Number.isSafeInteger(pid) || pid <= 0 || holdLockOwnerAlive(pid))
+        return false;
+    let second;
+    try {
+        second = fs.lstatSync(lockPath);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return true;
+        throw error;
+    }
+    if (second.dev !== first.dev || second.ino !== first.ino || second.mtimeMs !== first.mtimeMs)
+        return false;
+    try {
+        fs.unlinkSync(lockPath);
+        return true;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return true;
+        throw error;
+    }
+}
+/** Serialize the read-modify-write cycle so concurrent set/release calls cannot overwrite each other. */
+export async function withRepoMergeHoldRecordLock(recordPath, action) {
+    const lockPath = `${recordPath}.lock`;
+    fs.mkdirSync(path.dirname(recordPath), { recursive: true });
+    const started = Date.now();
+    let fd;
+    let ownedStat;
+    while (fd === undefined) {
+        try {
+            fd = fs.openSync(lockPath, "wx", 0o600);
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            if (Date.now() - started >= HOLD_LOCK_WAIT_MS) {
+                throw new LanesError("repo_hold_write_busy", "This repository hold is being updated; retry the command", { path: recordPath });
+            }
+            if (!removeStaleHoldLock(lockPath)) {
+                await new Promise((resolve) => setTimeout(resolve, 10));
+            }
+            continue;
+        }
+        try {
+            ownedStat = fs.fstatSync(fd);
+            fs.writeSync(fd, `${process.pid}\n${Date.now()}\n`);
+        }
+        catch (error) {
+            try {
+                fs.closeSync(fd);
+            }
+            catch (closeError) {
+                process.stderr.write(`hq lanes hold: lock close failed for ${lockPath}: ${closeError instanceof Error ? closeError.message : String(closeError)}\n`);
+            }
+            try {
+                const current = fs.lstatSync(lockPath);
+                if (!ownedStat || (current.dev === ownedStat.dev && current.ino === ownedStat.ino))
+                    fs.unlinkSync(lockPath);
+            }
+            catch (cleanupError) {
+                if (cleanupError.code !== "ENOENT") {
+                    process.stderr.write(`hq lanes hold: lock cleanup failed for ${lockPath}: ${cleanupError instanceof Error ? cleanupError.message : String(cleanupError)}\n`);
+                }
+            }
+            throw error;
+        }
+    }
+    try {
+        return await action();
+    }
+    finally {
+        try {
+            fs.closeSync(fd);
+        }
+        catch (error) {
+            process.stderr.write(`hq lanes hold: lock close failed for ${lockPath}: ${error instanceof Error ? error.message : String(error)}\n`);
+        }
+        try {
+            const current = fs.lstatSync(lockPath);
+            if (ownedStat && current.dev === ownedStat.dev && current.ino === ownedStat.ino)
+                fs.unlinkSync(lockPath);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT") {
+                process.stderr.write(`hq lanes hold: lock cleanup failed for ${lockPath}: ${error instanceof Error ? error.message : String(error)}\n`);
+            }
+        }
+    }
+}
+function historyEntry(hold) {
+    return {
+        set_at: hold.set_at,
+        until: hold.until,
+        reason: hold.reason,
+        set_by_lane: hold.set_by_lane,
+        set_by_session: hold.set_by_session,
+        ...(hold.released_at ? { released_at: hold.released_at } : {}),
+        ...(hold.released_reason ? { released_reason: hold.released_reason } : {}),
+    };
+}
+function holdView(hold, now) {
+    const expired = Date.parse(hold.until) <= now.getTime();
+    return { ...hold, expired, active: !expired && hold.released_at === undefined };
+}
+function sameCompany(left, right) {
+    return left !== null && left.uid === right.uid && left.slug === right.slug;
+}
+function notifyRunningLocalLanes(hqRoot, company, text) {
+    const warnings = [];
+    let laneIds;
+    try {
+        laneIds = listLaneIds(hqRoot);
+    }
+    catch (error) {
+        return [`Could not list running lanes for dropbox notification: ${error instanceof Error ? error.message : String(error)}`];
+    }
+    for (const laneId of laneIds) {
+        try {
+            const lane = readLane(hqRoot, laneId);
+            if (lane.state !== "running" || lane.host.kind !== "local" || !sameCompany(lane.company, company))
+                continue;
+            appendDropboxMessage(hqRoot, lane.lane_id, { text });
+        }
+        catch (error) {
+            warnings.push(`Could not notify lane ${laneId}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    return warnings;
+}
+function reportNotificationWarnings(warnings) {
+    for (const warning of warnings)
+        console.error(`hq lanes hold: ${warning}`);
+}
+function splitCommandChain(command) {
+    const segments = [];
+    let current = "";
+    let quote = null;
+    let escaped = false;
+    for (let index = 0; index < command.length; index += 1) {
+        const character = command[index] ?? "";
+        if (escaped) {
+            current += character;
+            escaped = false;
+            continue;
+        }
+        if (character === "\\" && quote !== "'") {
+            current += character;
+            escaped = true;
+            continue;
+        }
+        if (quote) {
+            current += character;
+            if (character === quote)
+                quote = null;
+            continue;
+        }
+        if (character === "'" || character === "\"") {
+            quote = character;
+            current += character;
+            continue;
+        }
+        if (character === ";" || character === "|") {
+            segments.push(current.trim());
+            current = "";
+            if (character === "|" && command[index + 1] === "|")
+                index += 1;
+            continue;
+        }
+        if (character === "&" && command[index + 1] === "&") {
+            segments.push(current.trim());
+            current = "";
+            index += 1;
+            continue;
+        }
+        current += character;
+    }
+    if (quote !== null || escaped) {
+        return fail("repo_hold_command_invalid", "Command has an unclosed quote or escape");
+    }
+    segments.push(current.trim());
+    return segments.filter(Boolean);
+}
+function shellWords(segment) {
+    const words = [];
+    let current = "";
+    let quote = null;
+    let escaped = false;
+    for (const character of segment) {
+        if (escaped) {
+            current += character;
+            escaped = false;
+            continue;
+        }
+        if (character === "\\" && quote !== "'") {
+            escaped = true;
+            continue;
+        }
+        if (quote) {
+            if (character === quote)
+                quote = null;
+            else
+                current += character;
+            continue;
+        }
+        if (character === "'" || character === "\"") {
+            quote = character;
+            continue;
+        }
+        if (/\s/.test(character)) {
+            if (current)
+                words.push(current);
+            current = "";
+            continue;
+        }
+        current += character;
+    }
+    if (escaped)
+        current += "\\";
+    if (current)
+        words.push(current);
+    return words;
+}
+function optionRepo(words) {
+    for (let index = 0; index < words.length; index += 1) {
+        const word = words[index] ?? "";
+        if ((word === "-R" || word === "--repo") && words[index + 1])
+            return words[index + 1] ?? null;
+        if (word.startsWith("--repo="))
+            return word.slice("--repo=".length);
+        if (word.startsWith("-R") && word.length > 2)
+            return word.slice(2);
+    }
+    return null;
+}
+function ghPrSubcommand(words) {
+    const groupIndex = words.indexOf("pr", 1);
+    if (groupIndex < 0)
+        return null;
+    for (let index = groupIndex + 1; index < words.length; index += 1) {
+        const word = words[index] ?? "";
+        if (word === "-R" || word === "--repo" || word === "--hostname") {
+            index += 1;
+            continue;
+        }
+        if (word.startsWith("--repo=") || (word.startsWith("-R") && word.length > 2))
+            continue;
+        if (word.startsWith("-"))
+            continue;
+        return { groupIndex, subcommand: word };
+    }
+    return { groupIndex, subcommand: null };
+}
+const SHELL_ASSIGNMENT = /^[A-Za-z_][A-Za-z0-9_]*=/;
+const PR_MERGE_VALUE_OPTIONS = new Set([
+    "-A", "--author-email", "-b", "--body", "-F", "--body-file",
+    "--match-head-commit", "-t", "--subject",
+]);
+const PR_MERGE_INLINE_VALUE_OPTIONS = [
+    "--author-email=", "--body=", "--body-file=", "--match-head-commit=", "--subject=",
+];
+function skipEnvOptions(words, start) {
+    let index = start + 1;
+    while (index < words.length) {
+        const word = words[index] ?? "";
+        if (SHELL_ASSIGNMENT.test(word)) {
+            index += 1;
+            continue;
+        }
+        if (word === "-i" || word === "--ignore-environment") {
+            index += 1;
+            continue;
+        }
+        if (word === "-u" || word === "--unset" || word === "-C" || word === "--chdir") {
+            index += 2;
+            continue;
+        }
+        if (word.startsWith("--unset=") || word.startsWith("--chdir=")) {
+            index += 1;
+            continue;
+        }
+        if (word === "--")
+            return index + 1;
+        if (word.startsWith("-")) {
+            index += 1;
+            continue;
+        }
+        break;
+    }
+    return index;
+}
+function skipTimeoutOptions(words, start) {
+    let index = start + 1;
+    while (index < words.length) {
+        const word = words[index] ?? "";
+        if (word === "--") {
+            index += 1;
+            break;
+        }
+        if (word === "-k" || word === "--kill-after" || word === "-s" || word === "--signal") {
+            index += 2;
+            continue;
+        }
+        if (word.startsWith("--kill-after=") || word.startsWith("--signal=")) {
+            index += 1;
+            continue;
+        }
+        if (word === "--preserve-status" || word === "--foreground" || word === "--verbose" || word === "-v") {
+            index += 1;
+            continue;
+        }
+        if (word.startsWith("-")) {
+            index += 1;
+            continue;
+        }
+        break;
+    }
+    // timeout always takes a duration before the wrapped command.
+    return Math.min(index + 1, words.length);
+}
+function unwrapCommand(words) {
+    let index = 0;
+    while (index < words.length) {
+        if (SHELL_ASSIGNMENT.test(words[index] ?? "")) {
+            index += 1;
+            continue;
+        }
+        if (words[index] === "env") {
+            index = skipEnvOptions(words, index);
+            continue;
+        }
+        if (words[index] === "timeout") {
+            index = skipTimeoutOptions(words, index);
+            continue;
+        }
+        break;
+    }
+    return words.slice(index);
+}
+function pullRequestUrlRepo(words, start) {
+    for (let index = start; index < words.length; index += 1) {
+        const word = words[index] ?? "";
+        if (PR_MERGE_VALUE_OPTIONS.has(word)) {
+            index += 1;
+            continue;
+        }
+        if (PR_MERGE_INLINE_VALUE_OPTIONS.some((option) => word.startsWith(option)))
+            continue;
+        if (word.startsWith("-"))
+            continue;
+        if (!/^https?:\/\//i.test(word))
+            return null;
+        let url;
+        try {
+            url = new URL(word);
+        }
+        catch {
+            continue;
+        }
+        const match = /^\/([^/]+)\/([^/]+)\/pull\/\d+\/?$/.exec(url.pathname);
+        if (!match)
+            continue;
+        try {
+            return canonicalRepo(`${decodeURIComponent(match[1] ?? "")}/${decodeURIComponent(match[2] ?? "")}`);
+        }
+        catch {
+            return fail("repo_hold_repo_invalid", "Pull request URL has an invalid repository", { field: "repo" });
+        }
+    }
+    return null;
+}
+function checkedMerge(segment) {
+    const words = unwrapCommand(shellWords(segment));
+    if (words[0] === "git" && words.slice(1).includes("merge"))
+        return { repo_unresolved: true };
+    if (words[0] !== "gh")
+        return null;
+    const pr = ghPrSubcommand(words);
+    if (pr?.subcommand === "merge") {
+        const rawRepo = optionRepo(words) ?? pullRequestUrlRepo(words, pr.groupIndex + 2);
+        if (!rawRepo)
+            return { repo_unresolved: true };
+        return { repo: canonicalRepo(rawRepo) };
+    }
+    const apiIndex = words.indexOf("api", 1);
+    if (apiIndex < 0)
+        return null;
+    const rest = words.slice(apiIndex + 1);
+    const graphql = rest.includes("graphql");
+    if (graphql && rest.some((word) => word.includes("mergePullRequest"))) {
+        // gh api does not accept gh's inherited -R/--repo flag. GraphQL merge input
+        // identifies the target by pull-request node ID, which cannot be resolved
+        // to a repository without a network read, so this command stays unresolved.
+        return { repo_unresolved: true };
+    }
+    for (const word of rest) {
+        const match = /^(?:https?:\/\/api\.github\.com)?\/?repos\/([^/]+)\/([^/]+)\/pulls\/\d+\/merge\/?$/.exec(word);
+        if (match)
+            return { repo: canonicalRepo(`${match[1]}/${match[2]}`) };
+    }
+    return null;
+}
+function printJson(value) {
+    console.log(JSON.stringify(value));
+}
+export function registerLaneRepoMergeHoldCommand(lanes, deps, wrap) {
+    const hold = lanes.command("hold").description("Set and enforce repository merge holds");
+    hold.command("set <repo>")
+        .description("Set or replace a repository merge hold")
+        .requiredOption("--company <slug>", "Company that owns this repository hold")
+        .requiredOption("--reason <text>", "Why merges are held")
+        .requiredOption("--until <time>", "Expiry as an ISO timestamp or duration such as 4h")
+        .action(wrap(async (repoArg, options) => {
+        const repo = canonicalRepo(repoArg);
+        const company = await deps.resolveCompany(options.company);
+        const reason = nonEmptyText("reason", options.reason);
+        const env = deps.env;
+        const hqRoot = deps.hqRoot();
+        const hold = await withRepoMergeHoldRecordLock(holdFilePath(hqRoot, repo), () => {
+            const now = deps.now();
+            const until = parseUntil(options.until, now);
+            const previous = readHold(hqRoot, repo);
+            if (previous && (previous.company.uid !== company.uid || previous.company.slug !== company.slug)) {
+                fail("repo_hold_company_mismatch", `A merge hold for ${repo} belongs to another company`, { repo });
+            }
+            const next = {
+                schema_version: HOLD_SCHEMA_VERSION,
+                repo,
+                company,
+                reason,
+                set_at: now.toISOString(),
+                until,
+                set_by_lane: env.HQ_LANE_ID?.trim() || null,
+                set_by_session: sessionIdFromEnv(env) ?? null,
+                history: [...(previous?.history ?? []), ...(previous ? [historyEntry(previous)] : [])].slice(-HISTORY_CAP),
+            };
+            writeHold(hqRoot, next);
+            return next;
+        });
+        const notificationWarnings = notifyRunningLocalLanes(hqRoot, company, `Merge hold on ${repo} until ${hold.until}: ${reason}. \`hq lanes hold check\` can refuse merges when the \`${LANES_REPO_MERGE_HOLD_FLAG}\` gate is enabled.`);
+        reportNotificationWarnings(notificationWarnings);
+        printJson({ action: "lanes.hold.set", hold, ...(notificationWarnings.length ? { notification_warnings: notificationWarnings } : {}) });
+    }));
+    hold.command("list")
+        .description("List active and expired repository merge holds")
+        .option("--json", "Print JSON")
+        .action(wrap(async () => {
+        const now = deps.now();
+        printJson({ action: "lanes.hold.list", holds: listHolds(deps.hqRoot()).map((item) => holdView(item, now)) });
+    }));
+    hold.command("show <repo>")
+        .description("Show a repository merge hold")
+        .action(wrap(async (repoArg) => {
+        const repo = canonicalRepo(repoArg);
+        const record = readHold(deps.hqRoot(), repo);
+        if (!record)
+            fail("repo_hold_not_found", `No merge hold exists for ${repo}`, { repo });
+        printJson({ action: "lanes.hold.show", hold: holdView(record, deps.now()) });
+    }));
+    hold.command("release <repo>")
+        .description("Release an existing repository merge hold")
+        .requiredOption("--reason <text>", "Why the hold is being released")
+        .action(wrap(async (repoArg, options) => {
+        const repo = canonicalRepo(repoArg);
+        const reason = nonEmptyText("reason", options.reason);
+        const hqRoot = deps.hqRoot();
+        const released = await withRepoMergeHoldRecordLock(holdFilePath(hqRoot, repo), () => {
+            const existing = readHold(hqRoot, repo);
+            if (!existing)
+                fail("repo_hold_not_found", `No merge hold exists for ${repo}`, { repo });
+            if (existing.released_at)
+                fail("repo_hold_already_released", `Merge hold for ${repo} is already released`, { repo });
+            const next = {
+                ...existing,
+                released_at: deps.now().toISOString(),
+                released_reason: reason,
+            };
+            writeHold(hqRoot, next);
+            return next;
+        });
+        const notificationWarnings = notifyRunningLocalLanes(hqRoot, released.company, `Merge hold on ${repo} released: ${reason}.`);
+        reportNotificationWarnings(notificationWarnings);
+        printJson({
+            action: "lanes.hold.release",
+            hold: holdView(released, deps.now()),
+            ...(notificationWarnings.length ? { notification_warnings: notificationWarnings } : {}),
+        });
+    }));
+    hold.command("check")
+        .description("Refuse merge commands targeting an actively held repository")
+        .requiredOption("--command <shell-command>", "Command to inspect without executing it")
+        .option("--json", "Print JSON")
+        .action(wrap(async (options) => {
+        if (!options.command.trim())
+            fail("repo_hold_command_empty", "Command to check must not be empty");
+        if (readLanesFlagLocalOverride(LANES_REPO_MERGE_HOLD_FLAG, deps.env) === false) {
+            printJson({ ok: true, hold_enforcement: "off" });
+            return;
+        }
+        let unresolved = false;
+        let gateWasOff = false;
+        try {
+            const repos = [];
+            for (const segment of splitCommandChain(options.command)) {
+                const checked = checkedMerge(segment);
+                if (!checked)
+                    continue;
+                if ("repo_unresolved" in checked) {
+                    unresolved = true;
+                    continue;
+                }
+                repos.push(checked.repo);
+            }
+            const now = deps.now();
+            const activeHolds = [...new Set(repos)]
+                .map((repo) => readHold(deps.hqRoot(), repo))
+                .filter((existing) => existing !== null && holdView(existing, now).active);
+            let deniedHold;
+            for (const existing of activeHolds) {
+                const enabled = await (deps.mergeHoldEnabled ?? ((company) => readLanesRegistryFlag(LANES_REPO_MERGE_HOLD_FLAG, { company, env: deps.env })))(existing.company);
+                if (!enabled) {
+                    gateWasOff = true;
+                    continue;
+                }
+                deniedHold ??= existing;
+            }
+            if (deniedHold) {
+                printJson({
+                    ok: false,
+                    error: "repo_merge_held",
+                    repo: deniedHold.repo,
+                    reason: deniedHold.reason,
+                    until: deniedHold.until,
+                });
+                process.exitCode = 3;
+                return;
+            }
+            printJson({
+                ok: true,
+                ...(gateWasOff ? { hold_enforcement: "off" } : {}),
+                ...(unresolved ? { repo_unresolved: true } : {}),
+            });
+        }
+        catch (error) {
+            if (!(error instanceof LanesError))
+                throw error;
+            console.error(`hq lanes hold check: ${LANES_REPO_MERGE_HOLD_FLAG} could not verify this command (${error.error}); allowing it`);
+            printJson({
+                ok: true,
+                check_error: error.error,
+                ...(gateWasOff ? { hold_enforcement: "off" } : {}),
+                ...(unresolved ? { repo_unresolved: true } : {}),
+            });
+        }
+    }));
+}
+//# sourceMappingURL=lanes-hold.js.map

package/dist/commands/lanes.js

@@ -21,6 +21,7 @@ import { registerOutpostPrunerCommand } from "./outpost-pruner.js";
 import { registerLaneChecksCommand } from "./lanes-checks.js";
 import { registerLaneReportCommands } from "./lanes-report.js";
 import { registerLaneTrackerImportCommand } from "./lanes-import.js";
+import { registerLaneRepoMergeHoldCommand } from "./lanes-hold.js";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
 import { resolveLanesHqRoot } from "../lib/lanes/hq-root.js";
 import { isSsmRunCommandProcess } from "../lib/lanes/ssm-command-context.js";
@@ -6892,6 +6893,12 @@ export function registerLanesCommand(parent, deps = {}) {
             return body;
         },
     }, wrap);
+    registerLaneRepoMergeHoldCommand(lanes, {
+        hqRoot: ctx.hqRoot,
+        resolveCompany: ctx.resolveCompany,
+        now: ctx.now,
+        env: ctx.env,
+    }, wrap);
     registerOutpostPrunerCommand(lanes);
     const noStoryOption = new Option("--no-story <reason>", "Create a lane without a story and record why");
     noStoryOption.attributeName = () => "noStory";

package/dist/lib/lanes/registry-flag.d.ts

@@ -17,6 +17,7 @@ export interface ReadLanesFlagOptions {
     getToken?: () => string | Promise<string>;
     reportFailure?: (error: unknown) => void;
 }
+export declare function readLanesFlagLocalOverride(flagKey: string, env?: NodeJS.ProcessEnv): boolean | null;
 /**
  * Read a lanes flag once for each company identity in this CLI process. The
  * cache contains only an in-flight or settled boolean promise; it is never

package/dist/lib/lanes/registry-flag.js

@@ -3,6 +3,9 @@ import { ensureCognitoIdToken } from "../../utils/cognito-session.js";
 import { FLAG_REGISTRY_DEFAULT_ENDPOINT, resolveFlagRegistryEndpoint, } from "../flag-registry-endpoint.js";
 export const LANES_FLAG_API_DEFAULT_ENDPOINT = FLAG_REGISTRY_DEFAULT_ENDPOINT;
 export const LANES_FLAG_READ_TIMEOUT_MS = 5_000;
+export function readLanesFlagLocalOverride(flagKey, env = process.env) {
+    return readLocalOverride(flagKey, env);
+}
 const registryReads = new Map();
 class MissingFlagTokenError extends Error {
     constructor() {
@@ -37,7 +40,7 @@ function cacheKey(flagKey, company, endpoint) {
  */
 export async function readLanesRegistryFlag(flagKey, options = {}) {
     const env = options.env ?? process.env;
-    const localOverride = readLocalOverride(flagKey, env);
+    const localOverride = readLanesFlagLocalOverride(flagKey, env);
     if (localOverride !== null)
         return localOverride;
     const endpoint = resolveFlagRegistryEndpoint(undefined, env);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.256.0",
+  "version": "5.257.0",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {