@telora/daemon 0.23.14 → 0.23.16

package/dist/merge/candidate-rework.js

@@ -0,0 +1,152 @@
+// PINNED-BY-BEGIN (generated by gen:pinned-by -- do not hand-edit; checked by lint:pinned-by)
+// Pinned by: packages/daemon/src/merge/candidate-rework.test.ts,
+//   packages/daemon/src/merge/completion-conflict-rework.test.ts,
+//   packages/daemon/src/merge/completion-rework-armed.test.ts
+// PINNED-BY-END
+/**
+ * A completion merge that cannot proceed returns its focus to coding as re-work:
+ * a red (or verdict-less) integration candidate, a final merge of the
+ * integration tip that conflicts (aborted, never resolved by the daemon), or a
+ * conflict-deciding merge after the approved head. ONE Bug on the delivery that
+ * owns the work, and that done delivery re-opened through the single-writer
+ * reconciler (done -> verify_failed, the `integrationCandidateRed` fact). No
+ * escalation is filed: the failure is the focus's own work, read by its next
+ * coding pass. A conflict's Bug names the paths and the integration commits the
+ * branch lacks, the same work order the coding spawn's reconcile section gives
+ * (prompt-sections/integration-reconcile-section.ts).
+ *
+ * OWNER: the delivery named by the `Telora-Delivery` trailer of the newest
+ * non-merge commit on the branch that is one of the focus's done deliveries;
+ * else the most recently updated done delivery. One OPEN Bug per candidate commit
+ * and cause: its title carries the sha, an open one is not filed again, and when
+ * every earlier one is closed (the team closed it, yet the same commit is still
+ * failing) a numbered new attempt is filed, so the delivery always re-opens.
+ * The outcome says what was APPLIED; only a re-open or already-open work counts
+ * as returning the focus to coding.
+ *
+ * @module merge/candidate-rework
+ */
+import { DELIVERY_STATUS } from '@telora/daemon-core';
+import { resolveReconciledWrite } from '../delivery/delivery-reconciler-apply.js';
+import { candidateBranchForFocus } from '../ci/candidate-ref.js';
+import { createLogger } from '../log/daemon-log.js';
+const log = createLogger({ module: 'completion-merge' });
+/** The Bug's title; carries the commit so one failure files one Bug. Pure. */
+export function candidateReworkTitle(sha, cause) {
+    const short = sha.slice(0, 9);
+    if (cause === 'conflict')
+        return `Final merge of integration into ${short} conflicts`;
+    if (cause === 'unreviewed_merge')
+        return `Merge at ${short} decided a conflict no review judged`;
+    return `Integration candidate ${short} failed CI`;
+}
+function listed(items, empty) {
+    return items.length > 0 ? items.slice(0, 30).map((i) => `- ${i}`) : [`- ${empty}`];
+}
+function conflictDescription(subject, sha, conflict) {
+    const integration = conflict?.integrationBranch ?? 'integration';
+    return [
+        `Merging the ${integration} tip into the focus head ${sha} CONFLICTS. The daemon aborted the merge: deciding a ` +
+            'conflict changes code after the review approved HEAD, and CI only judges reviewed trees.',
+        '',
+        'Conflicting paths:',
+        ...listed(conflict?.conflictPaths ?? [], 'could not be read -- run the merge to see them'),
+        '',
+        `Commits on ${integration} the branch lacks:`,
+        ...listed(conflict?.missingCommits ?? [], 'could not be read'),
+        '',
+        `MERGE origin/${integration} into ${subject.branchName} (never rebase: the shas carry the Telora-Delivery ` +
+            'trailers and the per-commit verify verdicts), resolve each path, and commit. The resolved head then passes ' +
+            'the gate and review before the completion merge is tried again.',
+    ];
+}
+/** The Bug's description. Pure. */
+export function candidateReworkDescription(subject, sha, cause, conflict) {
+    if (cause === 'conflict')
+        return conflictDescription(subject, sha, conflict).join('\n');
+    if (cause === 'unreviewed_merge') {
+        return [
+            `The focus head ${sha} carries a merge after the approved head that decided a conflict (git's re-merge of it is ` +
+                'not empty), so its code was never reviewed and CI must not judge it as a candidate.',
+            '',
+            'Check the merge resolution on the branch, fix it if it is wrong, and commit; the head then passes the gate and ' +
+                'review before the completion merge is tried again.',
+        ].join('\n');
+    }
+    const what = cause === 'red'
+        ? `CI's full suite FAILED on the focus's integration candidate ${sha} (the focus branch merged with the integration tip).`
+        : `CI published no verdict for the focus's integration candidate ${sha} within the wait window.`;
+    return [
+        what,
+        '',
+        `Integration does not move until a candidate is green. Read the failing run with \`ci-logs\` (its ref is ` +
+            `refs/heads/${candidateBranchForFocus(subject.focusId)}), fix it on ${subject.branchName}, and commit; ` +
+            'the next review and candidate run judge the fix.',
+    ].join('\n');
+}
+/** Which done delivery owns the re-work. Pure. */
+export function chooseReworkOwner(deliveries, trailers) {
+    const done = deliveries.filter((d) => d.executionStatus === DELIVERY_STATUS.DONE);
+    for (const t of trailers) {
+        const owner = done.find((d) => d.id === t);
+        if (owner)
+            return owner;
+    }
+    return [...done].sort((a, b) => (b.updatedAt ?? '').localeCompare(a.updatedAt ?? ''))[0] ?? null;
+}
+const CLOSED_ISSUE_STATUSES = new Set(['Done', 'Verified']);
+/** The Bug to file for this candidate, or null when one is still open. Pure. */
+export function nextReworkTitle(issues, base) {
+    const family = issues.filter((i) => i.title === base || i.title.startsWith(`${base} (attempt `));
+    if (family.some((i) => !CLOSED_ISSUE_STATUSES.has(i.status)))
+        return null;
+    return family.length === 0 ? base : `${base} (attempt ${family.length + 1})`;
+}
+/** Re-open the done owner when the reconciler, given its issues, moves it off done. */
+async function reopenOwner(owner, issues, deps) {
+    const decision = resolveReconciledWrite({
+        input: {
+            currentStatus: DELIVERY_STATUS.DONE,
+            issues: issues.map((i) => ({ status: i.status, issueType: i.issueType, ...(i.deferrable ? { deferrable: true } : {}) })),
+            gitState: { worktreeCommitted: true },
+            guardVerdict: null,
+            reviewState: null,
+            integrationCandidateRed: true,
+        },
+    });
+    if (decision.target === DELIVERY_STATUS.DONE)
+        return false;
+    const stageId = await deps.resolveStageId(owner.id, decision.target);
+    await deps.updateDeliveryStatus(owner.id, decision.target, stageId, undefined, undefined, {
+        organizationId: deps.organizationId,
+        fromStatus: DELIVERY_STATUS.DONE,
+    });
+    return true;
+}
+/**
+ * File the candidate's Bug on its owner and re-open that delivery; say what was
+ * applied. Throws on a failed read or write (the driver retries).
+ */
+export async function routeCandidateRework(subject, sha, cause, conflict, deps) {
+    const deliveries = await deps.getFocusDeliveries(subject.focusId);
+    if (deliveries.some((d) => d.executionStatus !== DELIVERY_STATUS.DONE && d.executionStatus !== DELIVERY_STATUS.CANCELLED))
+        return 'already_open';
+    const owner = chooseReworkOwner(deliveries, deps.listBranchDeliveryTrailers(subject.repoPath, subject.branchName));
+    if (owner === null) {
+        log.warn(`[completion-merge] "${subject.focusName}": no done delivery to carry the re-work for candidate ${sha.slice(0, 9)}`);
+        return 'not_reopened';
+    }
+    let issues = await deps.getDeliveryIssues(owner.id);
+    const title = nextReworkTitle(issues, candidateReworkTitle(sha, cause));
+    if (title !== null) {
+        await deps.createIssue(owner.id, title, candidateReworkDescription(subject, sha, cause, conflict), 'Bug', 'P0');
+        issues = await deps.getDeliveryIssues(owner.id);
+    }
+    if (!(await reopenOwner(owner, issues, deps))) {
+        log.warn(`[completion-merge] "${subject.focusName}": "${owner.name}" stays done -- the reconciler re-opened nothing for ${sha.slice(0, 9)}`);
+        return 'not_reopened';
+    }
+    log.info(`[completion-merge] "${subject.focusName}": re-opened "${owner.name}" with the candidate's Bug`);
+    return 'reopened';
+}
+//# sourceMappingURL=candidate-rework.js.map

package/dist/merge/candidate-rework.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"candidate-rework.js","sourceRoot":"","sources":["../../src/merge/candidate-rework.ts"],"names":[],"mappings":"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"}

package/dist/merge/completion-hold-record.d.ts

@@ -0,0 +1,20 @@
+/** The record file for a focus; `dir` defaults to the global state dir. Exported for tests. */
+export declare function completionHoldPath(productId: string, focusId: string, dir?: string): string;
+/**
+ * The instant the focus's completion merge was first held, stamping `now` when
+ * no record exists yet. Null when the record is unreadable or cannot be written.
+ */
+export declare function stampCompletionHold(productId: string, focusId: string, now: number, dir?: string): number | null;
+/** The candidate-wait file for a focus. Exported for tests. */
+export declare function candidateWaitPath(productId: string, focusId: string, dir?: string): string;
+/**
+ * When the focus's candidate `sha` was first stamped, stamping `now` when the
+ * record is absent, names another sha, or is CORRUPT (repaired: a malformed
+ * record would otherwise stop the no-verdict window from ever expiring). Null
+ * only when the record cannot be written; the driver then counts from its own
+ * first sighting.
+ */
+export declare function stampCandidateWait(productId: string, focusId: string, sha: string, now: number, dir?: string): number | null;
+/** Forget the focus's first hold and candidate wait (it merged, or it is no longer complete). Best-effort. */
+export declare function clearCompletionHold(productId: string, focusId: string, dir?: string): void;
+//# sourceMappingURL=completion-hold-record.d.ts.map

package/dist/merge/completion-hold-record.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"completion-hold-record.d.ts","sourceRoot":"","sources":["../../src/merge/completion-hold-record.ts"],"names":[],"mappings":"AA4CA,+FAA+F;AAC/F,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,GAAE,MAAkB,GAAG,MAAM,CAEtG;AAgBD;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,GAAE,MAAkB,GAAG,MAAM,GAAG,IAAI,CAW3H;AAED,+DAA+D;AAC/D,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,GAAE,MAAkB,GAAG,MAAM,CAErG;AAmBD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,GAAE,MAAkB,GAAG,MAAM,GAAG,IAAI,CAavI;AAED,8GAA8G;AAC9G,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,GAAE,MAAkB,GAAG,IAAI,CAOrG"}

package/dist/merge/completion-hold-record.js

@@ -0,0 +1,130 @@
+// PINNED-BY-BEGIN (generated by gen:pinned-by -- do not hand-edit; checked by lint:pinned-by)
+// Pinned by: packages/daemon/src/merge/completion-hold-record.test.ts,
+//   packages/daemon/src/merge/completion-merge-driver.test.ts
+// PINNED-BY-END
+/**
+ * When a COMPLETED focus's integration merge was first held, recorded durably.
+ *
+ * Under completion-only merging (merge/completion-merge-gate.ts) a focus branch
+ * ahead of integration while its focus codes is normal; what can be stuck is a
+ * complete focus whose merge keeps being held. The stuck-branch surface
+ * (merge/merge-back-loop.ts) counts from THIS instant: the first merge-back tick
+ * that saw the focus complete and its merge held stamps it, every later tick
+ * reads it back, a successful merge or the focus re-opening (it is no longer
+ * complete) clears it. One file per (product, focus) under the global state dir,
+ * written atomically (temp + rename), so a daemon restart neither resets nor
+ * re-arms the clock -- and no delivery row write moves it (a row's updated_at
+ * would).
+ *
+ * The same directory holds the CANDIDATE WAIT: when the focus's integration
+ * candidate (a sha) was first pushed or seen waiting on CI, so the completion
+ * merge driver's no-verdict window (merge/completion-merge-driver.ts) survives a
+ * restart. A new candidate sha restarts it; clearing the hold clears it too.
+ *
+ * Host-local like the auto-approval record (merge/review-auto-approval-record.ts):
+ * the daemon that claims the product writes and reads it. A hold record that
+ * cannot be read or written yields null -- nothing is filed that tick, and it is
+ * logged. A corrupt candidate-wait record is repaired (rewritten), so the
+ * no-verdict window can always expire; an unwritable one yields null.
+ *
+ * @module merge/completion-hold-record
+ */
+import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { resolveGlobalStateDir } from '../daemon-state/daemon-process.js';
+import { createLogger } from '../log/daemon-log.js';
+const log = createLogger({ module: 'completion-merge' });
+function holdDir() {
+    return resolve(resolveGlobalStateDir(), 'completion-holds');
+}
+/** The record file for a focus; `dir` defaults to the global state dir. Exported for tests. */
+export function completionHoldPath(productId, focusId, dir = holdDir()) {
+    return resolve(dir, `${productId}-${focusId}.json`.replace(/[^a-zA-Z0-9._-]/g, '_'));
+}
+function readFirstHeldAt(path) {
+    let raw;
+    try {
+        raw = readFileSync(path, 'utf8');
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return 'absent';
+        throw err;
+    }
+    const parsed = JSON.parse(raw);
+    if (typeof parsed !== 'object' || parsed === null)
+        return null;
+    const at = parsed.firstHeldAt;
+    return typeof at === 'number' && Number.isFinite(at) ? at : null;
+}
+/**
+ * The instant the focus's completion merge was first held, stamping `now` when
+ * no record exists yet. Null when the record is unreadable or cannot be written.
+ */
+export function stampCompletionHold(productId, focusId, now, dir = holdDir()) {
+    const path = completionHoldPath(productId, focusId, dir);
+    try {
+        const existing = readFirstHeldAt(path);
+        if (existing !== 'absent')
+            return existing;
+        writeAtomic(dir, path, { productId, focusId, firstHeldAt: now });
+        return now;
+    }
+    catch (err) {
+        log.warn(`[completion-merge] completion-hold record for focus ${focusId} unusable: ${err.message}`);
+        return null;
+    }
+}
+/** The candidate-wait file for a focus. Exported for tests. */
+export function candidateWaitPath(productId, focusId, dir = holdDir()) {
+    return completionHoldPath(productId, `${focusId}-candidate`, dir);
+}
+function writeAtomic(dir, path, body) {
+    mkdirSync(dir, { recursive: true });
+    const tmp = `${path}.${process.pid}.tmp`;
+    writeFileSync(tmp, JSON.stringify(body));
+    renameSync(tmp, path);
+}
+/** The candidate a readable wait record names, or null when absent, unreadable or malformed. */
+function readCandidateWait(path) {
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf8'));
+        return typeof parsed === 'object' && parsed !== null ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * When the focus's candidate `sha` was first stamped, stamping `now` when the
+ * record is absent, names another sha, or is CORRUPT (repaired: a malformed
+ * record would otherwise stop the no-verdict window from ever expiring). Null
+ * only when the record cannot be written; the driver then counts from its own
+ * first sighting.
+ */
+export function stampCandidateWait(productId, focusId, sha, now, dir = holdDir()) {
+    const path = candidateWaitPath(productId, focusId, dir);
+    const existing = readCandidateWait(path);
+    if (existing !== null && existing.sha === sha && typeof existing.since === 'number' && Number.isFinite(existing.since)) {
+        return existing.since;
+    }
+    try {
+        writeAtomic(dir, path, { productId, focusId, sha, since: now });
+        return now;
+    }
+    catch (err) {
+        log.warn(`[completion-merge] candidate-wait record for focus ${focusId} cannot be written: ${err.message}`);
+        return null;
+    }
+}
+/** Forget the focus's first hold and candidate wait (it merged, or it is no longer complete). Best-effort. */
+export function clearCompletionHold(productId, focusId, dir = holdDir()) {
+    try {
+        rmSync(completionHoldPath(productId, focusId, dir), { force: true });
+        rmSync(candidateWaitPath(productId, focusId, dir), { force: true });
+    }
+    catch (err) {
+        log.warn(`[completion-merge] completion-hold record for focus ${focusId} could not be cleared: ${err.message}`);
+    }
+}
+//# sourceMappingURL=completion-hold-record.js.map

package/dist/merge/completion-hold-record.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"completion-hold-record.js","sourceRoot":"","sources":["../../src/merge/completion-hold-record.ts"],"names":[],"mappings":"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"}

package/dist/merge/completion-merge-driver.d.ts

@@ -0,0 +1,96 @@
+/**
+ * The one driver of a held completion merge: the merge-back loop hands it the
+ * gate's hold (merge/completion-merge-gate.ts) and it takes the step that
+ * advances the focus toward integration.
+ *
+ *   merge_out       -> merge the integration tip into the focus branch ONCE, with
+ *                      git's automatic merge (merge/focus-merge.ts
+ *                      attemptCompletionMergeOut). A clean merge stays and is the
+ *                      next candidate. A merge that conflicts is aborted and is
+ *                      re-work: deciding a conflict changes code after the review
+ *                      approved HEAD, and CI must only judge reviewed trees, so the
+ *                      team resolves it and its head passes the gate and review.
+ *   review_merge    -> a merge after the approved head already decided a conflict:
+ *                      re-work, so review judges that head.
+ *   push_candidate  -> push the head to the focus's candidate branch so CI runs the
+ *                      full suite on exactly that commit (ci/candidate-ref.ts).
+ *   wait_ci         -> nothing, until CANDIDATE_CI_VERDICT_WAIT_MS has passed with
+ *                      no verdict; then the missing verdict is re-work like a red.
+ *                      The wait is counted from a DURABLE stamp of the candidate
+ *                      (merge/completion-hold-record.ts), so a daemon restart
+ *                      neither restarts nor forgets the window.
+ *   rework          -> return the focus to coding: one Bug on the owning delivery,
+ *                      re-opened to verify_failed (merge/candidate-rework.ts). No
+ *                      escalation is filed.
+ *
+ * Integration never moves here; a green candidate is admitted by the gate and
+ * fast-forwarded by the caller's normal merge.
+ *
+ * @module merge/completion-merge-driver
+ */
+import type { CompletionMergeStep } from './completion-merge-gate.js';
+/** How long a pushed candidate may sit with no published verdict before it is re-work. */
+export declare const CANDIDATE_CI_VERDICT_WAIT_MS: number;
+/** The focus branch a step acts on. */
+export interface CompletionMergeSubject {
+    focusId: string;
+    focusName: string;
+    repoPath: string;
+    branchName: string;
+}
+/** Why a candidate is returned to the focus as re-work. */
+export type CandidateReworkCause = 'red' | 'no_verdict' | 'conflict' | 'unreviewed_merge';
+/** What a conflicting final merge left for the team: the paths, and the integration commits the branch lacks. */
+export interface CompletionMergeConflict {
+    integrationBranch: string;
+    conflictPaths: string[];
+    /** `<sha9> <subject>`, newest first; [] when unreadable. */
+    missingCommits: string[];
+}
+/**
+ * What routing the re-work APPLIED: the done owner re-opened by a status write,
+ * work already open on the focus (nothing to re-open), or nothing re-opened (no
+ * owner, or the reconciler kept it done). Only the first two return the focus to coding.
+ */
+export type CandidateReworkOutcome = 'reopened' | 'already_open' | 'not_reopened';
+/** One completion merge-out: merged clean (or already current), conflicted (aborted), or could not run. */
+export type CompletionMergeOutOutcome = {
+    kind: 'merged';
+} | {
+    kind: 'conflict';
+    conflict: CompletionMergeConflict;
+} | {
+    kind: 'error';
+    message: string;
+};
+/** The driver's effects; bound at the composition root (composition/execution-merge-context.ts). */
+export interface CompletionMergeDriverDeps {
+    /** One automatic merge of the integration tip into the focus branch; a conflict is aborted, never resolved. */
+    mergeOut: () => Promise<CompletionMergeOutOutcome>;
+    /** Push `sha` to the focus's candidate branch; false when the push failed. */
+    pushCandidate: (repoPath: string, focusId: string, sha: string) => boolean;
+    /**
+     * When the focus's candidate `sha` was first pushed or seen waiting, stamping
+     * `now` when no stamp names `sha`. Durable across restarts (a corrupt record is
+     * repaired); null when the record cannot be written -- the driver then counts
+     * the wait from its own in-memory first sighting, so a missing verdict still
+     * becomes re-work.
+     */
+    candidateWaitSince: (sha: string, now: number) => number | null;
+    /** Return the focus to coding as re-work for the candidate at `sha`. */
+    routeRework: (subject: CompletionMergeSubject, sha: string, cause: CandidateReworkCause, conflict: CompletionMergeConflict | null) => Promise<CandidateReworkOutcome>;
+    now: () => number;
+}
+/** Reset the driver's memory -- tests start from a clean slate. */
+export declare function __resetCompletionMergeDriverForTests(): void;
+/** What a step did: whether it returned the focus to coding (the caller then files no stuck observation). */
+export interface CompletionMergeStepResult {
+    reworked: boolean;
+}
+/**
+ * Take the step a held completion merge names, and say whether it returned the
+ * focus to coding. Never throws: a failed step is retried next tick (and did not
+ * return the focus).
+ */
+export declare function driveCompletionMergeStep(subject: CompletionMergeSubject, step: CompletionMergeStep, headSha: string, deps: CompletionMergeDriverDeps): Promise<CompletionMergeStepResult>;
+//# sourceMappingURL=completion-merge-driver.d.ts.map

package/dist/merge/completion-merge-driver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"completion-merge-driver.d.ts","sourceRoot":"","sources":["../../src/merge/completion-merge-driver.ts"],"names":[],"mappings":"AASA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAKtE,0FAA0F;AAC1F,eAAO,MAAM,4BAA4B,QAAqB,CAAC;AAE/D,uCAAuC;AACvC,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,2DAA2D;AAC3D,MAAM,MAAM,oBAAoB,GAAG,KAAK,GAAG,YAAY,GAAG,UAAU,GAAG,kBAAkB,CAAC;AAE1F,iHAAiH;AACjH,MAAM,WAAW,uBAAuB;IACtC,iBAAiB,EAAE,MAAM,CAAC;IAC1B,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,4DAA4D;IAC5D,cAAc,EAAE,MAAM,EAAE,CAAC;CAC1B;AAED;;;;GAIG;AACH,MAAM,MAAM,sBAAsB,GAAG,UAAU,GAAG,cAAc,GAAG,cAAc,CAAC;AAElF,2GAA2G;AAC3G,MAAM,MAAM,yBAAyB,GACjC;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,GAClB;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,EAAE,uBAAuB,CAAA;CAAE,GACvD;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEvC,oGAAoG;AACpG,MAAM,WAAW,yBAAyB;IACxC,+GAA+G;IAC/G,QAAQ,EAAE,MAAM,OAAO,CAAC,yBAAyB,CAAC,CAAC;IACnD,8EAA8E;IAC9E,aAAa,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;IAC3E;;;;;;OAMG;IACH,kBAAkB,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;IAChE,wEAAwE;IACxE,WAAW,EAAE,CAAC,OAAO,EAAE,sBAAsB,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,oBAAoB,EAAE,QAAQ,EAAE,uBAAuB,GAAG,IAAI,KAAK,OAAO,CAAC,sBAAsB,CAAC,CAAC;IACtK,GAAG,EAAE,MAAM,MAAM,CAAC;CACnB;AAUD,mEAAmE;AACnE,wBAAgB,oCAAoC,IAAI,IAAI,CAE3D;AAED,6GAA6G;AAC7G,MAAM,WAAW,yBAAyB;IACxC,QAAQ,EAAE,OAAO,CAAC;CACnB;AAuDD;;;;GAIG;AACH,wBAAsB,wBAAwB,CAC5C,OAAO,EAAE,sBAAsB,EAC/B,IAAI,EAAE,mBAAmB,EACzB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,yBAAyB,GAC9B,OAAO,CAAC,yBAAyB,CAAC,CAgBpC"}

package/dist/merge/completion-merge-driver.js

@@ -0,0 +1,94 @@
+// PINNED-BY-BEGIN (generated by gen:pinned-by -- do not hand-edit; checked by lint:pinned-by)
+// Pinned by: packages/daemon/src/completion/team-exit/teardown-merge-gate.test.ts,
+//   packages/daemon/src/merge/candidate-rework.test.ts,
+//   packages/daemon/src/merge/completion-conflict-rework.test.ts,
+//   packages/daemon/src/merge/completion-merge-driver.test.ts,
+//   packages/daemon/src/merge/completion-rework-armed.test.ts,
+//   packages/daemon/src/merge/merge-back-loop.test.ts
+// PINNED-BY-END
+import { createLogger } from '../log/daemon-log.js';
+const log = createLogger({ module: 'completion-merge' });
+/** How long a pushed candidate may sit with no published verdict before it is re-work. */
+export const CANDIDATE_CI_VERDICT_WAIT_MS = 3 * 60 * 60 * 1000;
+/**
+ * The wait's fallback clock: when this process first saw each candidate waiting,
+ * read only when the durable record cannot be written. Re-work routing keeps no
+ * memory of its own: routeRework is idempotent (an open Bug is not refiled, a
+ * re-opened focus is incomplete, so the gate stops naming the step).
+ */
+const fallbackWaitSince = new Map();
+/** Reset the driver's memory -- tests start from a clean slate. */
+export function __resetCompletionMergeDriverForTests() {
+    fallbackWaitSince.clear();
+}
+function key(subject, sha) {
+    return `${subject.focusId}:${sha}`;
+}
+const CAUSE_TEXT = {
+    red: 'is RED in CI',
+    no_verdict: 'got no CI verdict',
+    conflict: 'conflicts with the integration tip',
+    unreviewed_merge: 'carries a conflict-deciding merge no review judged',
+};
+async function rework(subject, sha, cause, conflict, deps) {
+    const outcome = await deps.routeRework(subject, sha, cause, conflict);
+    if (outcome === 'not_reopened') {
+        log.warn(`[completion-merge] "${subject.focusName}": ${sha.slice(0, 9)} ${CAUSE_TEXT[cause]} but no work was re-opened -- retried next tick`);
+        return { reworked: false };
+    }
+    log.info(`[completion-merge] "${subject.focusName}": ${sha.slice(0, 9)} ${CAUSE_TEXT[cause]} -- returned to the focus as re-work (${outcome})`);
+    return { reworked: true };
+}
+const NOTHING = { reworked: false };
+async function mergeOut(subject, headSha, deps) {
+    const outcome = await deps.mergeOut();
+    if (outcome.kind === 'conflict')
+        return rework(subject, headSha, 'conflict', outcome.conflict, deps);
+    if (outcome.kind === 'error')
+        log.warn(`[completion-merge] "${subject.focusName}": merge-out could not run: ${outcome.message}`);
+    return NOTHING;
+}
+/** The in-memory first sighting of a candidate waiting, for when the durable record is unusable. */
+function fallbackSince(subject, sha, now) {
+    const k = key(subject, sha);
+    const since = fallbackWaitSince.get(k) ?? now;
+    fallbackWaitSince.set(k, since);
+    log.warn(`[completion-merge] "${subject.focusName}": the candidate-wait record is unusable; counting ${sha.slice(0, 9)}'s wait from this process's first sighting`);
+    return since;
+}
+/** wait_ci: re-work once the durable wait for `headSha` has run past the window. */
+async function waitForVerdict(subject, headSha, deps) {
+    const now = deps.now();
+    const since = deps.candidateWaitSince(headSha, now) ?? fallbackSince(subject, headSha, now);
+    if (now - since < CANDIDATE_CI_VERDICT_WAIT_MS)
+        return NOTHING;
+    return rework(subject, headSha, 'no_verdict', null, deps);
+}
+/**
+ * Take the step a held completion merge names, and say whether it returned the
+ * focus to coding. Never throws: a failed step is retried next tick (and did not
+ * return the focus).
+ */
+export async function driveCompletionMergeStep(subject, step, headSha, deps) {
+    try {
+        if (step === 'merge_out')
+            return await mergeOut(subject, headSha, deps);
+        if (step === 'review_merge')
+            return await rework(subject, headSha, 'unreviewed_merge', null, deps);
+        if (step === 'rework')
+            return await rework(subject, headSha, 'red', null, deps);
+        if (step === 'push_candidate') {
+            const pushed = deps.pushCandidate(subject.repoPath, subject.focusId, headSha);
+            if (pushed && deps.candidateWaitSince(headSha, deps.now()) === null)
+                fallbackSince(subject, headSha, deps.now());
+            log.info(`[completion-merge] "${subject.focusName}": ${pushed ? 'pushed' : 'could not push'} integration candidate ${headSha.slice(0, 9)} for CI`);
+            return NOTHING;
+        }
+        return await waitForVerdict(subject, headSha, deps);
+    }
+    catch (err) {
+        log.warn(`[completion-merge] "${subject.focusName}": ${step} for ${headSha.slice(0, 9)} failed: ${err.message}`);
+        return NOTHING;
+    }
+}
+//# sourceMappingURL=completion-merge-driver.js.map

package/dist/merge/completion-merge-driver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"completion-merge-driver.js","sourceRoot":"","sources":["../../src/merge/completion-merge-driver.ts"],"names":[],"mappings":"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"}

package/dist/merge/completion-merge-gate.d.ts

@@ -0,0 +1,71 @@
+import type { CiRunStatus } from '../ci/ci-status.js';
+import type { ApprovalGateState } from './approval-gate-state.js';
+import { type BranchMergeGateTarget, type GatedAnchor, type MergeGateTarget, type UnmergedCommit } from './merge-gate-coverage.js';
+/** The step that advances a held completion merge; driven by the merge-back loop only. */
+export type CompletionMergeStep = 'merge_out' | 'review_merge' | 'push_candidate' | 'wait_ci' | 'rework';
+/** A merge the gate holds (with why, and the step that advances it), or one it admits at an exact commit. */
+export type MergeGateDecision = {
+    hold: string;
+    next?: CompletionMergeStep;
+    headSha?: string;
+    /** The gate's OWN delivery read found the focus incomplete: there is no completion hold to age. */
+    incomplete?: true;
+} | {
+    hold: null;
+    admittedBy: string;
+    candidateSha: string;
+};
+/** One focus delivery, as the completion predicate reads it. */
+export interface CompletionDeliveryFact {
+    name: string;
+    executionStatus: string | null;
+}
+/**
+ * Injected reads. The production binding (git, the product-api, the verdict
+ * record and the CI status refs) is built at the composition root
+ * (composition/execution-merge-context.ts).
+ */
+export interface CompletionMergeGateDeps {
+    /** The focus's deliveries; throws when unreadable. */
+    getFocusDeliveries: (focusId: string) => Promise<CompletionDeliveryFact[]>;
+    /** integration..branch, newest first; null when git cannot list it. */
+    listUnmergedCommits: (repoPath: string, integrationBranch: string, branchName: string) => UnmergedCommit[] | null;
+    /** The anchor's full sha and its unmerged ancestry; null when git cannot resolve the sha. */
+    resolveAnchor: (repoPath: string, integrationBranch: string, sha: string) => Omit<GatedAnchor, 'source'> | null;
+    /** The commit the focus's newest current approval judged, null when none; throws when unreadable. */
+    readApprovedReviewSha: (target: MergeGateTarget) => Promise<string | null>;
+    /** The gate state at the commit an approval judged; throws when unreadable. */
+    judgeApprovalGate: (target: MergeGateTarget, sha: string) => Promise<ApprovalGateState>;
+    /** The branch's head sha; null when unreadable. */
+    resolveBranchHead: (repoPath: string, branchName: string) => string | null;
+    /** The integration tip the branch must contain (the remote tip when there is one); null when unreadable. */
+    resolveIntegrationTip: (target: MergeGateTarget) => string | null;
+    /** Whether `ancestor` is an ancestor-or-equal of `descendant`; false when git cannot tell. */
+    isAncestor: (repoPath: string, ancestor: string, descendant: string) => boolean;
+    /** The candidate commit's CI status (fail-closed: missing / unreadable -> 'unknown'). */
+    readCandidateStatus: (target: MergeGateTarget, sha: string) => CiRunStatus;
+    /** The sha the focus's candidate branch points at on the remote; null when none / unreadable. */
+    readPushedCandidateSha: (target: MergeGateTarget) => string | null;
+}
+/** Step 1: every delivery done (cancelled is not done), at least one delivery. Pure. */
+export declare function focusCompletionHold(deliveries: readonly CompletionDeliveryFact[]): string | null;
+/** The merges after the approved commit that git cannot prove clean (they decided a conflict, or edited). Pure. */
+export declare function unreviewedMergesAfter(commits: readonly UnmergedCommit[], approval: GatedAnchor): UnmergedCommit[];
+/**
+ * Step 2 over listed commits: everything after the approved commit must be a
+ * merge (an integration sync; one that is not clean is unreviewedMergesAfter's),
+ * and what the approval contains must be gated by it under the capture rule. Pure.
+ */
+export declare function approvedHeadHold(commits: readonly UnmergedCommit[], approval: GatedAnchor): string | null;
+/**
+ * Whether a merge of `target` holds (why, and the step that advances it) or is
+ * admitted (at which commit). Never throws: a failed read holds. Whether it holds
+ * is the merge_gate_coverage stop-registry row's decision.
+ */
+export declare function readMergeGateDecision(target: MergeGateTarget, deps: CompletionMergeGateDeps): Promise<MergeGateDecision>;
+/**
+ * The decision for a branch whose focus may be unknown. With no focus there is
+ * no completion to read, so the merge holds.
+ */
+export declare function readMergeGateDecisionForBranch(target: BranchMergeGateTarget, deps: CompletionMergeGateDeps): Promise<MergeGateDecision>;
+//# sourceMappingURL=completion-merge-gate.d.ts.map

package/dist/merge/completion-merge-gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"completion-merge-gate.d.ts","sourceRoot":"","sources":["../../src/merge/completion-merge-gate.ts"],"names":[],"mappings":"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"}