@deftai/directive-core 0.107.0 → 0.109.0

package/dist/resolution/package-manager.js

@@ -16,13 +16,17 @@
  *      gitignored / package-manager-invisible). Only the global, project-local,
  *      ephemeral, and upgrade command forms vary by package manager.
  *
- * Every function here is PURE (no I/O): detection consumes an injected fact-set
- * so the whole surface is unit-testable without touching the filesystem or env.
+ * Detection from an injected fact-set remains pure. The project resolver is the
+ * single filesystem boundary used by consumer gates so package.json and lockfile
+ * precedence cannot drift across callers (#3610).
  */
+import { readFileSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
 export const PACKAGE_MANAGERS = ["npm", "pnpm"];
 export const DEFAULT_PACKAGE_MANAGER = "npm";
 /** Canonical published engine package name. */
 export const ENGINE_PACKAGE = "@deftai/directive";
+const EXPLICIT_PACKAGE_MANAGER_RE = /^(npm|pnpm)(?:@[0-9A-Za-z][0-9A-Za-z._+/=-]*)?$/i;
 function normalizePackageManager(value) {
     const v = value.trim().toLowerCase();
     if (v.startsWith("pnpm"))
@@ -31,24 +35,221 @@ function normalizePackageManager(value) {
         return "npm";
     return null;
 }
+function normalizeExplicitPackageManager(value) {
+    const match = EXPLICIT_PACKAGE_MANAGER_RE.exec(value.trim());
+    const name = match?.[1]?.toLowerCase();
+    return name === "npm" || name === "pnpm" ? name : null;
+}
+function unsupportedPackageManager(value, source) {
+    if (source === "env-override") {
+        return {
+            ok: false,
+            source,
+            message: "Unsupported DEFT_PACKAGE_MANAGER value; supported managers are npm and pnpm.",
+        };
+    }
+    const safeValue = sanitizeSingleLineDiagnostic(JSON.stringify(value));
+    return {
+        ok: false,
+        source,
+        message: `Unsupported package manager ${safeValue} from package.json#packageManager; supported managers are npm and pnpm.`,
+    };
+}
+/** Human-readable, non-executable label for a resolution source. */
+export function packageManagerSourceLabel(source) {
+    switch (source) {
+        case "env-override":
+            return "DEFT_PACKAGE_MANAGER override";
+        case "package-manager-field":
+            return "packageManager field";
+        case "pnpm-lock":
+            return "pnpm-lock.yaml";
+        case "user-agent":
+            return "npm_config_user_agent";
+        case "default":
+            return "default";
+    }
+}
+/**
+ * Strict package-manager resolution for execution boundaries.
+ *
+ * Explicit override/declaration values fail closed when unsupported. The
+ * returned manager is a closed union and callers map it to fixed argv; raw
+ * package.json or environment text is never executable (#2761/#2765/#3610).
+ */
+function packageManagerConflictResolution() {
+    return {
+        ok: false,
+        source: "env-override",
+        message: "DEFT_PACKAGE_MANAGER conflicts with package.json#packageManager; the declaration is authoritative.",
+    };
+}
+function resolveExplicitOverride(override) {
+    if (override.trim() === "")
+        return null;
+    const packageManager = normalizeExplicitPackageManager(override);
+    if (packageManager === null)
+        return unsupportedPackageManager(override, "env-override");
+    return { ok: true, packageManager, source: "env-override" };
+}
+export function resolvePackageManager(input = {}) {
+    const env = input.env ?? {};
+    const override = env.DEFT_PACKAGE_MANAGER;
+    const overrideText = typeof override === "string" ? override : "";
+    const field = input.packageManagerField;
+    if (field != null && field.trim() !== "") {
+        const declared = normalizeExplicitPackageManager(field);
+        if (declared === null)
+            return unsupportedPackageManager(field, "package-manager-field");
+        if (overrideText.trim() !== "") {
+            const overridden = normalizeExplicitPackageManager(overrideText);
+            if (overridden !== null && overridden !== declared) {
+                return packageManagerConflictResolution();
+            }
+        }
+        return { ok: true, packageManager: declared, source: "package-manager-field" };
+    }
+    const overrideResolution = resolveExplicitOverride(overrideText);
+    if (overrideResolution !== null)
+        return overrideResolution;
+    if (input.pnpmLockPresent) {
+        return { ok: true, packageManager: "pnpm", source: "pnpm-lock" };
+    }
+    const userAgent = env.npm_config_user_agent;
+    if (typeof userAgent === "string" && userAgent.trim() !== "") {
+        const packageManager = normalizePackageManager(userAgent);
+        if (packageManager !== null) {
+            return { ok: true, packageManager, source: "user-agent" };
+        }
+    }
+    return { ok: true, packageManager: DEFAULT_PACKAGE_MANAGER, source: "default" };
+}
+function defaultReadText(path) {
+    try {
+        return readFileSync(path, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+}
+function defaultIsFile(path) {
+    try {
+        return statSync(path).isFile();
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return false;
+        throw error;
+    }
+}
+const UNSAFE_DIAGNOSTIC_CHARACTER = /[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/u;
+/** Render untrusted diagnostic text as one bounded terminal-safe line. */
+export function sanitizeSingleLineDiagnostic(text) {
+    const printable = [...text]
+        .map((character) => (UNSAFE_DIAGNOSTIC_CHARACTER.test(character) ? " " : character))
+        .join("")
+        .replace(/\s+/g, " ")
+        .trim();
+    const codePoints = [...printable];
+    return codePoints.length > 240 ? `${codePoints.slice(0, 237).join("")}...` : printable;
+}
+function singleLineErrorDetail(error) {
+    const raw = error instanceof Error ? error.message : String(error);
+    return sanitizeSingleLineDiagnostic(raw) || "unknown error";
+}
+/** Resolve a consumer project's package manager from package.json and lockfile facts. */
+export function resolveProjectPackageManager(options = {}) {
+    const projectRoot = resolve(options.projectRoot ?? process.cwd());
+    const env = options.env ?? process.env;
+    const readText = options.readText ?? defaultReadText;
+    const isFile = options.isFile ?? defaultIsFile;
+    const packageJsonPath = join(projectRoot, "package.json");
+    let packageManagerField = null;
+    let packageJsonText;
+    try {
+        packageJsonText = readText(packageJsonPath);
+    }
+    catch (error) {
+        const detail = singleLineErrorDetail(error);
+        return {
+            ok: false,
+            source: "package-json",
+            message: `Could not read package.json for package-manager selection: ${detail}`,
+        };
+    }
+    if (packageJsonText !== null) {
+        let parsed;
+        try {
+            parsed = JSON.parse(packageJsonText);
+        }
+        catch (error) {
+            const detail = singleLineErrorDetail(error);
+            return {
+                ok: false,
+                source: "package-json",
+                message: `Could not parse package.json for package-manager selection: ${detail}`,
+            };
+        }
+        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+            return {
+                ok: false,
+                source: "package-json",
+                message: "Could not parse package.json for package-manager selection: root must be an object.",
+            };
+        }
+        const packageRecord = parsed;
+        if (Object.hasOwn(packageRecord, "packageManager")) {
+            const field = packageRecord.packageManager;
+            if (typeof field !== "string" || field.trim() === "") {
+                return {
+                    ok: false,
+                    source: "package-manager-field",
+                    message: "package.json#packageManager must be a non-empty string naming npm or pnpm.",
+                };
+            }
+            packageManagerField = field;
+        }
+    }
+    if (packageManagerField !== null) {
+        return resolvePackageManager({ env, packageManagerField });
+    }
+    let pnpmLockPresent;
+    try {
+        pnpmLockPresent = isFile(join(projectRoot, "pnpm-lock.yaml"));
+    }
+    catch (error) {
+        const detail = singleLineErrorDetail(error);
+        return {
+            ok: false,
+            source: "project-filesystem",
+            message: `Could not inspect pnpm-lock.yaml for package-manager selection: ${detail}`,
+        };
+    }
+    return resolvePackageManager({
+        env,
+        pnpmLockPresent,
+    });
+}
 /**
  * Detect the active package manager. Precedence (first match wins):
- *   1. `DEFT_PACKAGE_MANAGER` env override
- *   2. `packageManager` field / Corepack shim
+ *   1. `packageManager` field / Corepack shim (authoritative when present)
+ *   2. `DEFT_PACKAGE_MANAGER` env override
  *   3. `pnpm-lock.yaml` present
  *   4. `npm_config_user_agent` (set by the manager that spawned the process)
  *   5. default: npm
  */
 export function detectPackageManager(input = {}) {
     const env = input.env ?? {};
-    const override = env.DEFT_PACKAGE_MANAGER;
-    if (typeof override === "string" && override.trim() !== "") {
-        const pm = normalizePackageManager(override);
+    if (input.packageManagerField != null && input.packageManagerField.trim() !== "") {
+        const pm = normalizePackageManager(input.packageManagerField);
         if (pm)
             return pm;
     }
-    if (input.packageManagerField != null && input.packageManagerField.trim() !== "") {
-        const pm = normalizePackageManager(input.packageManagerField);
+    const override = env.DEFT_PACKAGE_MANAGER;
+    if (typeof override === "string" && override.trim() !== "") {
+        const pm = normalizePackageManager(override);
         if (pm)
             return pm;
     }

package/dist/review-monitor/constants.d.ts

@@ -14,6 +14,13 @@ export declare const MONITORING_TIER_1 = 1;
 export declare const MONITORING_TIER_2 = 2;
 export declare const MONITORING_TIER_3 = 3;
 export declare const DEFAULT_STALE_MINUTES = 30;
+/** `kind:` value marking an advisory pass-open mark rather than an ownership lease (#3607). */
+export declare const PASS_MARKER_KIND = "pass";
+/**
+ * Advisory pass marks expire on read (#3607). Passes run in minutes, so an hour
+ * bounds an abandoned mark without needing a heartbeat.
+ */
+export declare const DEFAULT_PASS_STALE_MINUTES = 60;
 export declare const REVIEW_MONITOR_HELP: string;
 export declare const REGISTER_HELP: string;
 export declare const RELEASE_HELP: string;

package/dist/review-monitor/constants.js

@@ -14,6 +14,13 @@ export const MONITORING_TIER_1 = 1;
 export const MONITORING_TIER_2 = 2;
 export const MONITORING_TIER_3 = 3;
 export const DEFAULT_STALE_MINUTES = 30;
+/** `kind:` value marking an advisory pass-open mark rather than an ownership lease (#3607). */
+export const PASS_MARKER_KIND = "pass";
+/**
+ * Advisory pass marks expire on read (#3607). Passes run in minutes, so an hour
+ * bounds an abandoned mark without needing a heartbeat.
+ */
+export const DEFAULT_PASS_STALE_MINUTES = 60;
 export const REVIEW_MONITOR_HELP = "usage: task verify:review-monitor -- --pr <N> [options]\n" +
     "\n" +
     "Fail-closed gate: when Tier 1 (sub-agent primitive available), require an\n" +

package/dist/review-monitor/github-lease.d.ts

@@ -1,6 +1,6 @@
 import { type GhRestSeams } from "../scm/gh-rest.js";
 import { type IssueComment } from "../umbrella-current-shape/index.js";
-import { type ReviewOwnerComment } from "./lease-comment.js";
+import { type PassOpenComment, type PassOpenMarker, type ReviewOwnerComment } from "./lease-comment.js";
 export type { IssueComment };
 export interface ReviewOwnerGithubSeams extends GhRestSeams {
     readonly fetchComments?: (repo: string, pr: number) => IssueComment[] | {
@@ -42,4 +42,101 @@ export declare function deleteReviewOwnerComment(repo: string, commentId: number
     error: string;
 };
 export declare function resolveGitHubLogin(seams?: ReviewOwnerGithubSeams): string | null;
+/**
+ * Author trust boundary for `<!-- deft:review-owner -->` comments (#3607 / #2307).
+ *
+ * Ownership leases gate. `verify:review-monitor` and `verify:l4-owner` exit 0 on a live
+ * lease, so a forged lease defeats a fail-closed gate. `listReviewOwnerComments` above
+ * therefore admits only maintainer associations -- OWNER, MEMBER, COLLABORATOR. That
+ * filter is the single author-association check in the lease read path and it lives in
+ * `isMaintainerAuthored` / `MAINTAINER_ASSOCIATIONS`
+ * (`packages/core/src/umbrella-current-shape/index.ts`), which is why a search for
+ * `author_association` in this directory finds nothing.
+ *
+ * Pass marks do not gate. They tell an arriving agent that a pass is open and never
+ * block a write, so a forged mark costs at most an unnecessary courtesy. Pass marks are
+ * therefore read from every author association, including CONTRIBUTOR, which is what
+ * #3607 requires ("visible regardless of the author's trust association"). The field
+ * instance is real: comment 5429316778 on PR #3775 carries this marker and is
+ * CONTRIBUTOR-authored, so the lease filter hides it while this reader sees it.
+ */
+export declare function listPassMarkerComments(repo: string, issue: number, seams?: ReviewOwnerGithubSeams): PassOpenComment[] | {
+    error: string;
+};
+export interface ActivePassMarker {
+    readonly commentId: number;
+    readonly marker: PassOpenMarker;
+}
+/** Read the open mark on an issue thread; expired and cleared marks are ignored (#3607). */
+export declare function fetchActivePassMarker(repo: string, issue: number, options?: {
+    now?: Date;
+    seams?: ReviewOwnerGithubSeams;
+}): ActivePassMarker | null | {
+    error: string;
+};
+export interface OpenPassMarkerInput {
+    readonly repo: string;
+    readonly issue: number;
+    readonly owner: string;
+    readonly passKind: string;
+    readonly agentId?: string | null;
+    readonly ceiling?: string | null;
+    /**
+     * Comment id returned by a previous open, to refresh that same mark in place.
+     * Only the pass that created a comment ever writes it again, which is what keeps
+     * two concurrent passes from overwriting one another (#3607).
+     */
+    readonly commentId?: number | null;
+    readonly startedAt?: Date;
+    readonly staleMinutes?: number;
+    readonly seams?: ReviewOwnerGithubSeams;
+}
+export type OpenPassMarkerResult = {
+    readonly status: "opened" | "renewed" | "observed";
+    readonly commentId: number;
+    readonly marker: PassOpenMarker;
+} | {
+    readonly error: string;
+};
+/**
+ * Mark a pass open on an issue thread (#3607).
+ *
+ * A marker comment belongs to the one pass that created it. An open never edits a
+ * comment it did not create -- it creates its own, or reports the mark already there --
+ * so two concurrent passes can never overwrite each other's metadata, including two
+ * agents sharing one GitHub login. Refreshing an existing mark requires the `commentId`
+ * that open handed back, and the mark on that comment is re-read and checked against the
+ * caller before the write: a `commentId` taken from an `observed` result names another
+ * pass, so it is refused and the caller opens its own mark instead of overwriting.
+ *
+ * `observed` means a mark is already open on the thread. The caller is informed and MAY
+ * still write; nothing is held. Concurrent creates resolve oldest-comment-id wins, and
+ * the loser removes its own duplicate.
+ */
+export declare function openPassMarker(input: OpenPassMarkerInput): OpenPassMarkerResult;
+export interface ClosePassMarkerInput {
+    readonly repo: string;
+    readonly issue: number;
+    readonly owner: string;
+    /** Comment id from open. Without it, the oldest open mark this owner authored. */
+    readonly commentId?: number | null;
+    readonly endedAt?: Date;
+    readonly seams?: ReviewOwnerGithubSeams;
+}
+export type ClosePassMarkerResult = {
+    readonly status: "cleared" | "not-open" | "held-by-other";
+    readonly commentId: number | null;
+} | {
+    readonly error: string;
+};
+/**
+ * Clear the mark at synthesis (#3607).
+ *
+ * `ended_at` is rendered over the marker as just read from the thread, never over the
+ * snapshot the caller opened with, so closing does not resurrect stale pass metadata.
+ * A mark the thread does not prove is the caller's own -- another author's, another
+ * owner's, or one whose author GitHub did not report -- is reported back, never
+ * overwritten.
+ */
+export declare function closePassMarker(input: ClosePassMarkerInput): ClosePassMarkerResult;
 //# sourceMappingURL=github-lease.d.ts.map

package/dist/review-monitor/github-lease.js

@@ -1,13 +1,15 @@
 import { spawnSync } from "node:child_process";
-import { resolveBinary } from "../scm/binary.js";
+import { resolveBinaryForArgv } from "../scm/call-shape.js";
 import { DEFAULT_TIMEOUT_S, restDeleteComment, restGetUser, restPostComment, restUpdateComment, } from "../scm/gh-rest.js";
 import { SUBPROCESS_MAX_BUFFER } from "../subprocess/max-buffer.js";
 import { isMaintainerAuthored, parseCommentsFromGhStdout, } from "../umbrella-current-shape/index.js";
-import { mapCommentEntry } from "./lease-comment.js";
+import { DEFAULT_PASS_STALE_MINUTES, PASS_MARKER_KIND } from "./constants.js";
+import { computeExpiresAt, findActivePassComment, mapCommentEntry, mapPassCommentEntry, renderPassOpenComment, } from "./lease-comment.js";
 function defaultFetchComments(repo, pr, seams) {
-    const binary = resolveBinary(seams.whichFn);
     const path = `repos/${repo}/issues/${pr}/comments?per_page=100`;
-    const proc = spawnSync(binary, ["api", "--paginate", path], {
+    const apiArgs = ["--paginate", path];
+    const binary = resolveBinaryForArgv("api", apiArgs, seams.whichFn);
+    const proc = spawnSync(binary, ["api", ...apiArgs], {
         encoding: "utf8",
         maxBuffer: SUBPROCESS_MAX_BUFFER,
         timeout: DEFAULT_TIMEOUT_S * 1000,
@@ -103,4 +105,184 @@ export function resolveGitHubLogin(seams = {}) {
         return null;
     }
 }
+/**
+ * Author trust boundary for `<!-- deft:review-owner -->` comments (#3607 / #2307).
+ *
+ * Ownership leases gate. `verify:review-monitor` and `verify:l4-owner` exit 0 on a live
+ * lease, so a forged lease defeats a fail-closed gate. `listReviewOwnerComments` above
+ * therefore admits only maintainer associations -- OWNER, MEMBER, COLLABORATOR. That
+ * filter is the single author-association check in the lease read path and it lives in
+ * `isMaintainerAuthored` / `MAINTAINER_ASSOCIATIONS`
+ * (`packages/core/src/umbrella-current-shape/index.ts`), which is why a search for
+ * `author_association` in this directory finds nothing.
+ *
+ * Pass marks do not gate. They tell an arriving agent that a pass is open and never
+ * block a write, so a forged mark costs at most an unnecessary courtesy. Pass marks are
+ * therefore read from every author association, including CONTRIBUTOR, which is what
+ * #3607 requires ("visible regardless of the author's trust association"). The field
+ * instance is real: comment 5429316778 on PR #3775 carries this marker and is
+ * CONTRIBUTOR-authored, so the lease filter hides it while this reader sees it.
+ */
+export function listPassMarkerComments(repo, issue, seams = {}) {
+    const fetcher = seams.fetchComments ?? ((r, n) => defaultFetchComments(r, n, seams));
+    const fetched = fetcher(repo, issue);
+    if (!Array.isArray(fetched)) {
+        return fetched;
+    }
+    const comments = [];
+    for (const entry of fetched) {
+        const mapped = mapPassCommentEntry({
+            id: entry.id,
+            body: entry.body,
+            created_at: entry.updatedAt,
+            author_login: entry.authorLogin,
+        });
+        if (mapped !== null) {
+            comments.push(mapped);
+        }
+    }
+    return comments;
+}
+/** Read the open mark on an issue thread; expired and cleared marks are ignored (#3607). */
+export function fetchActivePassMarker(repo, issue, options = {}) {
+    const listed = listPassMarkerComments(repo, issue, options.seams ?? {});
+    if (!Array.isArray(listed)) {
+        return { error: listed.error };
+    }
+    const active = findActivePassComment(listed, { now: options.now });
+    if (active === null || active.marker === null) {
+        return null;
+    }
+    return { commentId: active.id, marker: active.marker };
+}
+function buildPassMarker(input, startedAt) {
+    return {
+        kind: PASS_MARKER_KIND,
+        pass_kind: input.passKind,
+        owner: input.owner,
+        agent_id: input.agentId ?? null,
+        ceiling: input.ceiling ?? null,
+        started_at: startedAt.toISOString(),
+        expires_at: computeExpiresAt(startedAt, input.staleMinutes ?? DEFAULT_PASS_STALE_MINUTES),
+        ended_at: null,
+    };
+}
+function resolvePassCreateRace(input, createdId, marker, now, seams) {
+    const relisted = listPassMarkerComments(input.repo, input.issue, seams);
+    if (!Array.isArray(relisted)) {
+        return { error: relisted.error };
+    }
+    const winner = findActivePassComment(relisted, { now });
+    if (winner === null || winner.marker === null || winner.id === createdId) {
+        return { status: "opened", commentId: createdId, marker };
+    }
+    const deleted = deleteReviewOwnerComment(input.repo, createdId, seams);
+    if ("error" in deleted) {
+        return { error: deleted.error };
+    }
+    return { status: "observed", commentId: winner.id, marker: winner.marker };
+}
+/**
+ * Proof, read from the thread, that a mark is the caller's own to write (#3607).
+ *
+ * Both the comment's GitHub author and the marker's `owner` must be the caller. An
+ * author GitHub did not report is refused rather than assumed: an unreported author is
+ * exactly the case where a marker body claiming the caller as `owner` is unverifiable,
+ * and PATCHing another user's comment is a 403 for a non-maintainer.
+ */
+function isOwnOpenPassComment(comment, owner) {
+    const mark = comment.marker;
+    return (mark !== null &&
+        mark.ended_at === null &&
+        comment.authorLogin.length > 0 &&
+        comment.authorLogin === owner &&
+        mark.owner === owner);
+}
+/**
+ * A refresh must name the pass it refreshes (#3607). Owner login, agent id and pass kind
+ * identify a pass; the ceiling and the expiry window are what a refresh moves. Two runs
+ * agreeing on all three are one pass identity by construction, so a refresh then moves
+ * only that pass's own window.
+ */
+function refreshesSamePass(marker, input) {
+    return marker.pass_kind === input.passKind && marker.agent_id === (input.agentId ?? null);
+}
+/**
+ * Mark a pass open on an issue thread (#3607).
+ *
+ * A marker comment belongs to the one pass that created it. An open never edits a
+ * comment it did not create -- it creates its own, or reports the mark already there --
+ * so two concurrent passes can never overwrite each other's metadata, including two
+ * agents sharing one GitHub login. Refreshing an existing mark requires the `commentId`
+ * that open handed back, and the mark on that comment is re-read and checked against the
+ * caller before the write: a `commentId` taken from an `observed` result names another
+ * pass, so it is refused and the caller opens its own mark instead of overwriting.
+ *
+ * `observed` means a mark is already open on the thread. The caller is informed and MAY
+ * still write; nothing is held. Concurrent creates resolve oldest-comment-id wins, and
+ * the loser removes its own duplicate.
+ */
+export function openPassMarker(input) {
+    const seams = input.seams ?? {};
+    const startedAt = input.startedAt ?? new Date();
+    const marker = buildPassMarker(input, startedAt);
+    const body = renderPassOpenComment(marker);
+    const listed = listPassMarkerComments(input.repo, input.issue, seams);
+    if (!Array.isArray(listed)) {
+        return { error: listed.error };
+    }
+    if (input.commentId !== undefined && input.commentId !== null) {
+        const target = listed.find((comment) => comment.id === input.commentId);
+        if (target !== undefined &&
+            isOwnOpenPassComment(target, input.owner) &&
+            refreshesSamePass(target.marker, input)) {
+            const updated = updateReviewOwnerComment(input.repo, target.id, body, seams);
+            if ("error" in updated) {
+                return { error: updated.error };
+            }
+            return { status: "renewed", commentId: target.id, marker };
+        }
+    }
+    const active = findActivePassComment(listed, { now: startedAt });
+    if (active !== null && active.marker !== null) {
+        return { status: "observed", commentId: active.id, marker: active.marker };
+    }
+    const created = createReviewOwnerComment(input.repo, input.issue, body, seams);
+    if ("error" in created) {
+        return { error: created.error };
+    }
+    return resolvePassCreateRace(input, created.id, marker, startedAt, seams);
+}
+/**
+ * Clear the mark at synthesis (#3607).
+ *
+ * `ended_at` is rendered over the marker as just read from the thread, never over the
+ * snapshot the caller opened with, so closing does not resurrect stale pass metadata.
+ * A mark the thread does not prove is the caller's own -- another author's, another
+ * owner's, or one whose author GitHub did not report -- is reported back, never
+ * overwritten.
+ */
+export function closePassMarker(input) {
+    const seams = input.seams ?? {};
+    const endedAt = input.endedAt ?? new Date();
+    const listed = listPassMarkerComments(input.repo, input.issue, seams);
+    if (!Array.isArray(listed)) {
+        return { error: listed.error };
+    }
+    const target = input.commentId !== undefined && input.commentId !== null
+        ? (listed.find((comment) => comment.id === input.commentId) ?? null)
+        : findActivePassComment(listed, { now: endedAt });
+    if (target === null || target.marker === null || target.marker.ended_at !== null) {
+        return { status: "not-open", commentId: null };
+    }
+    if (!isOwnOpenPassComment(target, input.owner)) {
+        return { status: "held-by-other", commentId: target.id };
+    }
+    const body = renderPassOpenComment({ ...target.marker, ended_at: endedAt.toISOString() });
+    const updated = updateReviewOwnerComment(input.repo, target.id, body, seams);
+    if ("error" in updated) {
+        return { error: updated.error };
+    }
+    return { status: "cleared", commentId: target.id };
+}
 //# sourceMappingURL=github-lease.js.map

package/dist/review-monitor/lease-comment.d.ts

@@ -1,3 +1,4 @@
+import { PASS_MARKER_KIND } from "./constants.js";
 import type { PlatformPrimitive } from "./tier-detection.js";
 export declare function parseIso8601Utc(value: string): Date | null;
 export interface ReviewOwnerLease {
@@ -33,4 +34,39 @@ export declare function findActiveLeaseComment(comments: readonly ReviewOwnerCom
     now?: Date;
     headSha?: string | null;
 }): ReviewOwnerComment | null;
+/**
+ * Advisory pass-open mark on an issue thread (#3607).
+ *
+ * Observe-and-mark only: it records that a pass is open, who owns it, the declared
+ * ceiling comment, and when the mark expires. It never holds, blocks, or gates
+ * another actor's write -- an arriving agent reads it and decides for itself.
+ */
+export interface PassOpenMarker {
+    readonly kind: typeof PASS_MARKER_KIND;
+    readonly pass_kind: string;
+    readonly owner: string;
+    readonly agent_id: string | null;
+    readonly ceiling: string | null;
+    readonly started_at: string;
+    readonly expires_at: string;
+    readonly ended_at: string | null;
+}
+export interface PassOpenComment {
+    readonly id: number;
+    readonly body: string;
+    readonly createdAt: string;
+    /** GitHub login that authored the comment; "" when the source did not report one. */
+    readonly authorLogin: string;
+    readonly marker: PassOpenMarker | null;
+}
+export declare function parsePassOpenMarker(body: string): PassOpenMarker | null;
+export declare function renderPassOpenComment(marker: PassOpenMarker): string;
+/** Expired or synthesis-cleared marks are ignored on read; a mark self-clears (#3607). */
+export declare function isPassMarkerActive(marker: PassOpenMarker, now?: Date): boolean;
+export declare function mapPassCommentEntry(entry: unknown): PassOpenComment | null;
+/** Oldest comment id wins when two marks race, matching the lease (#2814 / #3607). */
+export declare function selectWinningPassComment(comments: readonly PassOpenComment[]): PassOpenComment | null;
+export declare function findActivePassComment(comments: readonly PassOpenComment[], options?: {
+    now?: Date;
+}): PassOpenComment | null;
 //# sourceMappingURL=lease-comment.d.ts.map