@deksden-com/dd-flow-cli 0.9.0-beta.11 → 0.9.0-beta.111

package/dist/services/lanes.js

@@ -1,6 +1,4 @@
 import crypto from "node:crypto";
-import fs from "node:fs";
-import path from "node:path";
 import { spawnSync } from "node:child_process";
 import { AppError } from "../shared/errors.js";
 import { appendAudit } from "./audit.js";
@@ -8,6 +6,31 @@ import { requireProjectByRoot } from "./projects.js";
 import { resolveProjectRoot } from "../storage/paths.js";
 const defaultTtlSeconds = 300;
 const defaultPollIntervalSeconds = 10;
+export function prepareLaneWaitTiming(input) {
+    return {
+        timeoutSeconds: normalizeNonNegativeNumber(input.timeoutSeconds, 0, "timeout"),
+        pollIntervalSeconds: normalizePositiveNumber(input.pollIntervalSeconds, defaultPollIntervalSeconds, "poll-interval")
+    };
+}
+export function prepareLaneLock(context, input, action) {
+    if (typeof input.workerId !== "string" || !input.workerId.trim())
+        throw new AppError("validation", "Lane lock requires a nonempty worker ID", 2);
+    if (["acquire", "release", "wait-acquire"].includes(action) && (typeof input.reason !== "string" || !input.reason.trim()))
+        throw new AppError("validation", "Lane lock requires a nonempty reason", 2);
+    if (input.leaseToken !== undefined && (typeof input.leaseToken !== "string" || !input.leaseToken.trim()))
+        throw new AppError("validation", "Lease token must be nonempty text", 2);
+    const ttlSeconds = normalizePositiveNumber(input.ttlSeconds, defaultTtlSeconds, "ttl");
+    const { timeoutSeconds, pollIntervalSeconds } = prepareLaneWaitTiming(input);
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const lane = normalizeLane(input.lane);
+    const workspace = input.workspacePath !== undefined ? requireMatchingLaneWorkspace(context, project.id, lane, input.workspacePath) : undefined;
+    if (input.workspacePath === undefined && ["acquire", "wait", "wait-acquire"].includes(action))
+        throw new AppError("validation", "Lane lock requires a workspace path", 2);
+    if (action === "acquire" || action === "wait-acquire")
+        assertWorkerMayAcquireLaneLock(context, project.id, lane, input.workerId);
+    const lock = action === "heartbeat" || action === "release" ? requireOwnedActiveLock(context, project.id, lane, input.workerId, input.leaseToken) : undefined;
+    return { project, lane, ttlSeconds, timeoutSeconds, pollIntervalSeconds, lock, workspace };
+}
 export function getLaneStatus(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
     return {
@@ -23,10 +46,16 @@ export function expireProjectLaneLocks(context, projectId) {
 export function expireProjectLaneWaiters(context, projectId) {
     expireStaleWaiters(context, projectId);
 }
-export function setLaneWorkspace(context, input) {
+export function prepareLaneWorkspace(context, input) {
+    if (input.branch !== undefined && (typeof input.branch !== "string" || !input.branch.trim()))
+        throw new AppError("validation", "Expected branch must be nonempty text", 2);
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
     const lane = normalizeLane(input.lane);
     const workspacePath = resolveExistingPath(input.workspacePath);
+    return { project, lane, workspacePath };
+}
+export function setLaneWorkspace(context, input) {
+    const { project, lane, workspacePath } = prepareLaneWorkspace(context, input);
     const now = context.now();
     const existing = laneRecord(context, project.id, lane);
     context.db.run(`INSERT INTO lanes
@@ -69,11 +98,12 @@ export function checkLaneWorkspace(context, input) {
     };
 }
 export function acquireLaneLock(context, input) {
-    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
-    const lane = normalizeLane(input.lane);
-    requireMatchingLaneWorkspace(context, project.id, lane, input.workspacePath);
-    assertWorkerMayAcquireLaneLock(context, project.id, lane, input.workerId);
-    const ttlSeconds = normalizePositiveNumber(input.ttlSeconds, defaultTtlSeconds, "ttl");
+    const prepared = prepareLaneLock(context, input, "acquire");
+    return context.db.writeTransaction(() => acquirePreparedLaneLock(context, input, prepared));
+}
+function acquirePreparedLaneLock(context, input, prepared) {
+    const { project, lane, ttlSeconds } = prepared;
+    assertPreparedLaneLock(context, prepared, input.workerId);
     expireStaleLocks(context, project.id);
     const active = activeLaneLock(context, project.id, lane);
     if (active) {
@@ -115,14 +145,15 @@ export function acquireLaneLock(context, input) {
         ...(expired ? { expired_lock_id: expired.id } : {})
     };
 }
+function assertPreparedLaneLock(context, prepared, workerId) {
+    if (JSON.stringify(laneRecord(context, prepared.project.id, prepared.lane)) !== JSON.stringify(prepared.workspace)
+        || context.db.get("SELECT root FROM projects WHERE id = ?", [prepared.project.id])?.root !== prepared.project.root)
+        throw new AppError("lane_workspace_changed", "Lane registration changed after workspace preparation", 1);
+    assertWorkerMayAcquireLaneLock(context, prepared.project.id, prepared.lane, workerId);
+}
 export function heartbeatLaneLock(context, input) {
-    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
-    const lane = normalizeLane(input.lane);
-    if (input.workspacePath) {
-        requireMatchingLaneWorkspace(context, project.id, lane, input.workspacePath);
-    }
-    const lock = requireOwnedActiveLock(context, project.id, lane, input.workerId, input.leaseToken);
-    const ttlSeconds = normalizePositiveNumber(input.ttlSeconds, defaultTtlSeconds, "ttl");
+    const { project, lock: preparedLock, ttlSeconds } = prepareLaneLock(context, input, "heartbeat");
+    const lock = preparedLock;
     const now = context.now();
     context.db.run(`UPDATE lane_locks SET heartbeat_at = ?, expires_at = ?, updated_at = ? WHERE id = ?`, [now, expiresAt(now, ttlSeconds), now, lock.id]);
     appendAudit(context, {
@@ -133,12 +164,8 @@ export function heartbeatLaneLock(context, input) {
     return { ok: true, lock: activeLaneLock(context, project.id, lock.lane) };
 }
 export function releaseLaneLock(context, input) {
-    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
-    const lane = normalizeLane(input.lane);
-    if (input.workspacePath) {
-        requireMatchingLaneWorkspace(context, project.id, lane, input.workspacePath);
-    }
-    const lock = requireOwnedActiveLock(context, project.id, lane, input.workerId, input.leaseToken);
+    const { project, lock: preparedLock } = prepareLaneLock(context, input, "release");
+    const lock = preparedLock;
     const now = context.now();
     context.db.run(`UPDATE lane_locks
      SET status = 'released', released_at = ?, reason = ?, updated_at = ?
@@ -152,11 +179,7 @@ export function releaseLaneLock(context, input) {
     return { ok: true, lock: laneLockById(context, lock.id) };
 }
 export async function waitForLaneLock(context, input) {
-    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
-    const lane = normalizeLane(input.lane);
-    requireMatchingLaneWorkspace(context, project.id, lane, input.workspacePath);
-    const timeoutSeconds = normalizeNonNegativeNumber(input.timeoutSeconds, 0, "timeout");
-    const pollIntervalSeconds = normalizePositiveNumber(input.pollIntervalSeconds, defaultPollIntervalSeconds, "poll-interval");
+    const { project, lane, timeoutSeconds, pollIntervalSeconds } = prepareLaneLock(context, input, "wait");
     const start = Date.now();
     while (true) {
         expireStaleLocks(context, project.id);
@@ -186,13 +209,18 @@ export function getLaneWaiters(context, input) {
         }))
     };
 }
-export function cancelLaneWaiter(context, input) {
+export function prepareLaneWaiterCancellation(context, input) {
+    if (typeof input.workerId !== "string" || !input.workerId.trim())
+        throw new AppError("validation", "Lane waiter requires a nonempty worker ID", 2);
+    if (typeof input.reason !== "string" || !input.reason.trim())
+        throw new AppError("validation", "lane waiter cancel requires --reason", 2);
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
     const lane = normalizeLane(input.lane);
     const reason = input.reason.trim();
-    if (!reason) {
-        throw new AppError("validation", "lane waiter cancel requires --reason", 2);
-    }
+    return { project, lane, reason };
+}
+export function cancelLaneWaiter(context, input) {
+    const { project, lane, reason } = prepareLaneWaiterCancellation(context, input);
     expireStaleWaiters(context, project.id);
     const now = context.now();
     const waiter = activeLaneWaiterForWorker(context, project.id, lane, input.workerId);
@@ -245,13 +273,7 @@ export function expireLaneWaiterById(context, input) {
     return { ok: true, expired: result.changes === 1, waiter_id: input.waiterId };
 }
 export async function waitAcquireLaneLock(context, input) {
-    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
-    const lane = normalizeLane(input.lane);
-    requireMatchingLaneWorkspace(context, project.id, lane, input.workspacePath);
-    assertWorkerMayAcquireLaneLock(context, project.id, lane, input.workerId);
-    const timeoutSeconds = normalizeNonNegativeNumber(input.timeoutSeconds, 0, "timeout");
-    const pollIntervalSeconds = normalizePositiveNumber(input.pollIntervalSeconds, defaultPollIntervalSeconds, "poll-interval");
-    const ttlSeconds = normalizePositiveNumber(input.ttlSeconds, defaultTtlSeconds, "ttl");
+    const { project, lane, timeoutSeconds, pollIntervalSeconds, ttlSeconds } = prepareLaneLock(context, input, "wait-acquire");
     const startedAt = Date.now();
     const waiterDeadline = timeoutSeconds > 0 ? new Date(startedAt + timeoutSeconds * 1000).toISOString() : null;
     while (true) {
@@ -375,10 +397,9 @@ function laneWaitersForProject(context, projectId, lane) {
      LIMIT 100`, [projectId]);
 }
 function activeLaneLock(context, projectId, lane) {
-    expireStaleLocks(context, projectId);
     return context.db.get(`SELECT * FROM lane_locks
-     WHERE project_id = ? AND lane = ? AND status = 'active'
-     ORDER BY updated_at DESC, id DESC LIMIT 1`, [projectId, lane]);
+     WHERE project_id = ? AND lane = ? AND status = 'active' AND expires_at > ?
+     ORDER BY updated_at DESC, id DESC LIMIT 1`, [projectId, lane, context.now()]);
 }
 function activeLaneWaiterForWorker(context, projectId, lane, workerId) {
     return context.db.get(`SELECT * FROM lane_waiters
@@ -513,13 +534,15 @@ function ensureQueuedLaneWaiter(context, input) {
     return waiter;
 }
 function tryAcquireQueuedLaneLock(context, input) {
-    expireStaleLocks(context, input.projectId);
-    expireStaleWaiters(context, input.projectId);
-    context.db.exec("BEGIN IMMEDIATE");
-    try {
+    const prepared = prepareLaneLock(context, input, "wait-acquire");
+    if (prepared.project.id !== input.projectId || prepared.lane !== input.lane)
+        throw new AppError("lane_workspace_changed", "Lane identity changed while waiting", 1);
+    return context.db.writeTransaction(() => {
+        assertPreparedLaneLock(context, prepared, input.workerId);
+        expireStaleLocks(context, input.projectId);
+        expireStaleWaiters(context, input.projectId);
         const existingLock = activeLaneLock(context, input.projectId, input.lane);
         if (existingLock?.worker_id === input.workerId) {
-            context.db.exec("COMMIT");
             return {
                 acquired: true,
                 payload: {
@@ -537,7 +560,6 @@ function tryAcquireQueuedLaneLock(context, input) {
         }
         const latest = latestLaneWaiterForWorker(context, input.projectId, input.lane, input.workerId);
         if (latest && ["cancelled", "expired"].includes(latest.status) && latest.updated_at >= input.invocationStartedAt) {
-            context.db.exec("COMMIT");
             return {
                 acquired: false,
                 payload: {
@@ -561,14 +583,14 @@ function tryAcquireQueuedLaneLock(context, input) {
         });
         const head = firstQueuedLaneWaiter(context, input.projectId, input.lane);
         if (!existingLock && head?.id === waiter.id) {
-            const lockResult = acquireLaneLock(context, {
+            const lockResult = acquirePreparedLaneLock(context, {
                 projectRoot: input.projectRoot,
                 lane: input.lane,
                 workerId: input.workerId,
                 workspacePath: input.workspacePath,
                 ttlSeconds: input.ttlSeconds,
                 reason: input.reason
-            });
+            }, prepared);
             const now = context.now();
             context.db.run(`UPDATE lane_waiters
          SET status = 'acquired', acquired_at = ?, updated_at = ?
@@ -580,7 +602,6 @@ function tryAcquireQueuedLaneLock(context, input) {
                 reason: input.reason,
                 payload: { project_id: input.projectId, lane: input.lane, worker_id: input.workerId, waiter_id: waiter.id }
             });
-            context.db.exec("COMMIT");
             return {
                 acquired: true,
                 payload: {
@@ -597,7 +618,6 @@ function tryAcquireQueuedLaneLock(context, input) {
             };
         }
         const position = queuedWaiterPosition(context, input.projectId, input.lane, waiter.id);
-        context.db.exec("COMMIT");
         return {
             acquired: false,
             payload: {
@@ -611,18 +631,10 @@ function tryAcquireQueuedLaneLock(context, input) {
                 position
             }
         };
-    }
-    catch (error) {
-        context.db.exec("ROLLBACK");
-        throw error;
-    }
+    });
 }
 function resolveExistingPath(value) {
-    const absolute = path.resolve(value);
-    if (!fs.existsSync(absolute)) {
-        throw new AppError("not_found", `Workspace path does not exist: ${absolute}`, 1);
-    }
-    return fs.realpathSync(absolute);
+    return resolveProjectRoot(value);
 }
 function detectBranch(workspacePath) {
     const result = spawnSync("git", ["-C", workspacePath, "rev-parse", "--abbrev-ref", "HEAD"], { encoding: "utf8" });
@@ -635,7 +647,7 @@ function expiresAt(now, ttlSeconds) {
     return new Date(new Date(now).getTime() + ttlSeconds * 1000).toISOString();
 }
 function normalizeLane(value) {
-    const normalized = value.trim().toLowerCase();
+    const normalized = typeof value === "string" ? value.trim().toLowerCase() : "";
     if (!normalized || !/^[a-z0-9._-]+$/.test(normalized)) {
         throw new AppError("validation", "Lane name must contain only lowercase letters, numbers, dot, underscore, or hyphen", 2);
     }
@@ -643,15 +655,16 @@ function normalizeLane(value) {
 }
 function normalizePositiveNumber(value, fallback, label) {
     const normalized = value ?? fallback;
-    if (!Number.isFinite(normalized) || normalized <= 0) {
-        throw new AppError("validation", `--${label} must be a positive number`, 2);
+    if (!Number.isFinite(normalized) || normalized <= 0 ||
+        (label === "poll-interval" ? normalized * 1000 > 2 ** 31 - 1 : !Number.isFinite(new Date(Date.now() + normalized * 1000).getTime()))) {
+        throw new AppError("validation", `--${label} must be a positive number within the supported timer/date range`, 2);
     }
     return normalized;
 }
 function normalizeNonNegativeNumber(value, fallback, label) {
     const normalized = value ?? fallback;
-    if (!Number.isFinite(normalized) || normalized < 0) {
-        throw new AppError("validation", `--${label} must be zero or a positive number`, 2);
+    if (!Number.isFinite(normalized) || normalized < 0 || !Number.isFinite(new Date(Date.now() + normalized * 1000).getTime())) {
+        throw new AppError("validation", `--${label} must be zero or a positive number within the supported date range`, 2);
     }
     return normalized;
 }

package/dist/services/lifecycle-command.js

@@ -1,11 +1,45 @@
 import path from "node:path";
 import { parse, quote } from "shell-quote";
+import { lifecycleOperationForArgv } from "./lifecycle-contract.js";
+/** Native hooks and the lightweight ingress must recognize the same shell. */
+export function lifecycleCommandFromPayload(payload) {
+    const input = payload.tool_input && typeof payload.tool_input === "object" ? payload.tool_input : {};
+    const command = [payload.command, input.command, input.cmd].find(value => typeof value === "string" && value.length > 0);
+    return typeof command === "string" ? unwrapShellCommand(command) : undefined;
+}
 const controlOperators = new Set(["&&", "||", ";", "|", "|&", "&", "(", ")", "<(", ">("]);
 const redirectionOperators = new Set(["<", ">", ">>", ">|", "<&", ">&", "<<<"]);
 /** Parse the deliberately small direct-command surface accepted by lifecycle hooks. */
 export function parseLifecycleCommand(command) {
     return parseLifecycleCommandInner(command, false);
 }
+/** Exact diagnostic routes; these deliberately confer no lifecycle authority. */
+export function continuationCommand(command) {
+    let entries;
+    try {
+        entries = parse(command, name => `$${name}`);
+    }
+    catch {
+        return null;
+    }
+    if (!entries.every(entry => typeof entry === "string"))
+        return null;
+    const words = entries;
+    const start = words.findIndex(word => ["stage", "work"].includes(word));
+    if (start < 1)
+        return null;
+    const launcher = words.slice(0, start);
+    while (launcher[0] && /^[A-Za-z_][A-Za-z0-9_]*=/.test(launcher[0]))
+        launcher.shift();
+    const direct = launcher.length === 1 && (path.basename(launcher[0]) === "dd-flow" || launcher[0] === "$DD_FLOW_BIN");
+    const node = launcher.length === 2 && path.basename(launcher[0]) === "node" && (path.basename(launcher[1]) === "cli.js" || launcher[1] === "$DD_FLOW_BIN");
+    if (!direct && !node)
+        return null;
+    const args = parseCommandArgs(words.slice(start));
+    const route = args.positional.slice(0, 3).join(" ");
+    const operation = route === "work repair add" ? "work_repair_add" : args.positional[0] === "stage" && args.positional[1] === "block" ? "stage_block" : null;
+    return operation ? { operation, args } : null;
+}
 /** Preserve the historical Desktop contract: execute the payload, not its one-command shell wrapper. */
 export function unwrapShellCommand(command) {
     let entries;
@@ -32,7 +66,7 @@ function parseLifecycleCommandInner(command, wrapped) {
     const heredoc = stripHeredocBodies(command);
     let entries;
     try {
-        entries = parse(heredoc.command, (name) => `$${name}`);
+        entries = parse(withoutFileDescriptors(heredoc.command), (name) => `$${name}`);
     }
     catch {
         // A command that cannot be tokenized cannot create a trusted claim. The
@@ -56,11 +90,11 @@ function parseLifecycleCommandInner(command, wrapped) {
     if (!found.length)
         return { kind: "none" };
     const first = found[0];
-    if (found.length !== 1 || composed || first.nestedCompound) {
+    if (found.length !== 1 || composed || first.nestedCompound || (heredoc.present && !heredoc.safe)) {
         return {
             kind: "compound",
             invocation: { ...first.invocation, rewriteSafe: false },
-            reason: found.length !== 1 ? "multiple_lifecycle_invocations" : first.nestedCompound ? "nested_compound_invocation" : "shell_composition"
+            reason: found.length !== 1 ? "multiple_lifecycle_invocations" : first.nestedCompound ? "nested_compound_invocation" : heredoc.present && !heredoc.safe ? "unsafe_heredoc" : "shell_composition"
         };
     }
     return { kind: "standalone", invocation: first.invocation };
@@ -126,8 +160,16 @@ function invocationFromSegment(segment, heredoc, wrapped, inheritedEnv) {
             index += 1;
         }
     }
-    const executable = segment.words[index];
-    if (!executable || path.basename(executable) !== "dd-flow")
+    let executable = segment.words[index];
+    let nodeLauncher = false;
+    let launcher;
+    if (executable && path.basename(executable) === "node"
+        && (path.basename(segment.words[index + 1] ?? "") === "cli.js" || segment.words[index + 1] === "$DD_FLOW_BIN")) {
+        launcher = executable;
+        executable = segment.words[++index];
+        nodeLauncher = true;
+    }
+    if (!executable || path.basename(executable) !== "dd-flow" && executable !== "$DD_FLOW_BIN" && !(nodeLauncher && path.basename(executable) === "cli.js"))
         return null;
     const argv = segment.words.slice(index + 1);
     const operation = lifecycleOperation(argv);
@@ -136,9 +178,10 @@ function invocationFromSegment(segment, heredoc, wrapped, inheritedEnv) {
     return {
         operation,
         executable,
+        ...(launcher ? { launcher } : {}),
         argv,
         env,
-        args: parseCommandArgs(argv.slice(2)),
+        args: parseCommandArgs(argv.slice(operation === "recovery_accept" ? 3 : 2)),
         command: quote(segment.words),
         rewriteSafe: !heredoc && !wrapped && !segment.dynamic,
         wrapped,
@@ -170,16 +213,7 @@ function wrappedInvocationFromSegment(segment) {
     return parseLifecycleCommandInner(payload, true);
 }
 function lifecycleOperation(argv) {
-    const key = `${argv[0] ?? ""} ${argv[1] ?? ""}`;
-    if (key === "session register")
-        return "session_register";
-    if (key === "stage start")
-        return "stage_start";
-    if (key === "stage resume")
-        return "stage_resume";
-    if (key === "work start")
-        return "work_start";
-    return null;
+    return lifecycleOperationForArgv(argv);
 }
 export function parseCommandArgs(argv) {
     const positional = [];
@@ -187,6 +221,12 @@ export function parseCommandArgs(argv) {
     for (let index = 0; index < argv.length; index += 1) {
         const value = argv[index];
         if (value?.startsWith("--")) {
+            const equals = value.indexOf("=");
+            if (equals > 2) {
+                const key = value.slice(2, equals);
+                options.set(key, [...(options.get(key) ?? []), value.slice(equals + 1)]);
+                continue;
+            }
             const key = value.slice(2);
             const next = argv[index + 1];
             const optionValue = !next || next.startsWith("--") ? "__dd_flow_flag__" : next;
@@ -213,6 +253,58 @@ export function commandPosition(invocation, index) {
 function assignment(word) {
     return /^[A-Za-z_][A-Za-z0-9_]*=/.test(word);
 }
+/** Source offsets matter: shell-quote loses the difference between `2>&1`
+ * and the literal argument `2 >&1`. Only inspect unquoted shell syntax. */
+function shellSyntaxOffsets(command) {
+    const offsets = [];
+    let quoted = null, escaped = false;
+    for (let i = 0; i < command.length; i++) {
+        const char = command[i];
+        if (escaped) {
+            escaped = false;
+            continue;
+        }
+        if (char === "\\" && quoted !== "'") {
+            escaped = true;
+            continue;
+        }
+        if (quoted) {
+            if (char === quoted)
+                quoted = null;
+            continue;
+        }
+        if (char === "'" || char === '"') {
+            quoted = char;
+            continue;
+        }
+        if (char === "#" && (i === 0 || /\s/.test(command[i - 1]))) {
+            offsets.push(i);
+            break;
+        }
+        if (char === "<" || char === ">")
+            offsets.push(i);
+    }
+    return offsets;
+}
+function descriptorStart(command, index) {
+    let start = index;
+    while (start > 0 && /[0-9]/.test(command[start - 1]))
+        start--;
+    return start === 0 || /[\s;&|]/.test(command[start - 1]) ? start : index;
+}
+export function shellSuffixOffset(command) {
+    const offset = shellSyntaxOffsets(command)[0];
+    return offset === undefined ? command.length : descriptorStart(command, offset);
+}
+function withoutFileDescriptors(command) {
+    for (const index of shellSyntaxOffsets(command).reverse()) {
+        if (command[index] === "#")
+            continue;
+        const start = descriptorStart(command, index);
+        command = command.slice(0, start) + command.slice(index);
+    }
+    return command;
+}
 function addAssignment(env, word) {
     const separator = word.indexOf("=");
     env[word.slice(0, separator)] = word.slice(separator + 1);
@@ -223,6 +315,7 @@ function stripHeredocBodies(command) {
     const pending = [];
     let active;
     let present = false;
+    let count = 0, quoted = true;
     for (const line of lines) {
         if (active) {
             const candidate = active.stripTabs ? line.replace(/^\t+/, "") : line;
@@ -233,13 +326,15 @@ function stripHeredocBodies(command) {
         if (line.trim())
             output.push(line);
         const found = heredocDelimiters(line);
+        count += found.length;
+        quoted &&= found.every(item => item.quoted);
         if (found.length) {
             present = true;
             active = found[0];
             pending.push(...found.slice(1));
         }
     }
-    return { command: output.join(" ; "), present };
+    return { command: output.join(" ; "), present, safe: count === 1 && quoted && !active && pending.length === 0 };
 }
 function heredocDelimiters(line) {
     const result = [];
@@ -282,7 +377,7 @@ function heredocDelimiters(line) {
                 index += 1;
         const delimiter = line.slice(start, index);
         if (delimiter)
-            result.push({ delimiter, stripTabs });
+            result.push({ delimiter, stripTabs, quoted: delimiterQuote !== null });
     }
     return result;
 }

package/dist/services/lifecycle-contract.js

@@ -0,0 +1,30 @@
+export const lifecycleRoutes = {
+    "session register": "session_register",
+    "stage start": "stage_start",
+    "stage finish": "stage_finish",
+    "stage pause": "stage_pause",
+    "stage resume": "stage_resume",
+    "work start": "work_start",
+    "work finish": "work_finish",
+    "work fail": "work_fail",
+    "merge apply": "merge_apply",
+    "merge repair": "merge_repair",
+    "run recovery accept": "recovery_accept"
+};
+export const lifecycleInternalOptions = ["invocation-id", "hook-event-id"];
+export function lifecycleOperationForArgv(argv) {
+    if (argv.some(arg => arg === "--help" || arg === "-h"))
+        return null;
+    for (const [route, operation] of Object.entries(lifecycleRoutes)) {
+        const parts = route.split(" ");
+        if (parts.every((part, index) => argv[index] === part))
+            return operation;
+    }
+    return null;
+}
+export function lifecycleRouteForOperation(operation) {
+    const entry = Object.entries(lifecycleRoutes).find(([, value]) => value === operation);
+    if (!entry)
+        throw new Error(`Unknown lifecycle operation: ${operation}`);
+    return entry[0];
+}