Skip to main content

magi/
queue.rs

1//! The task queue: what magi should do next, and who asked for it.
2//!
3//! The queue is what lets magi run unattended. `magi serve` takes the next
4//! task, runs the graph on it, records the outcome, and takes the next one.
5//!
6//! It is also the reason an agent can ask for work. `magi task add` is the
7//! whole interface, and it is the same command whether a human types it at a
8//! prompt, a phone posts it through the web UI, or an implementer inside a run
9//! shells out to it because it noticed something worth doing but out of scope.
10//! magi's CLI is the operating surface for both kinds of user; the queue is
11//! where their intentions meet.
12//!
13//! One task is one JSON file under [`Queue`]'s root. Files rather than a
14//! database because the operator has to be able to read, edit, and delete the
15//! backlog with the tools already on the machine, and because a crashed daemon
16//! must leave a queue the next one can pick up without recovery ceremony.
17//!
18//! # Shape
19//!
20//! [`Task`] is data plus *pure* state transitions - [`Task::fail`] decides
21//! whether an attempt was the last one, and touches no disk. [`Queue`] owns all
22//! I/O and is constructed with its root, so a test drives a real queue in a
23//! temp directory without setting a process-global home. Splitting them this
24//! way is why the retry policy below can be asserted directly.
25//!
26//! # Bounded by construction
27//!
28//! An autonomous loop that retries forever is a way to spend money on a task
29//! that cannot succeed. Every claim increments [`Task::attempts`]; a task that
30//! has burned its attempts becomes [`TaskStatus::Held`] and waits for a human
31//! rather than for another agent.
32
33use std::collections::HashMap;
34use std::num::NonZeroUsize;
35use std::path::{Path, PathBuf};
36
37use anyhow::{Context, Result, bail};
38use jiff::Timestamp;
39use serde::{Deserialize, Serialize};
40
41use crate::ask::Questions;
42use crate::id_reserve::{IdSource, path_exists};
43
44/// On-disk format for a queued task. Bumped when a field's meaning changes.
45///
46/// 21: task/chat command effect receipts commit atomically with local transitions.
47///
48/// 18: retained review criteria snapshots survive operator edits.
49///
50/// 17: durable explicit operator resumption, independent of run startup.
51///
52/// 7: added [`Task::attachments`], names of files copied under
53/// `<id>.attachments/` beside the task file (a field only; `#[serde(default)]`,
54/// so an older record reads as empty and [`read_path`] still accepts it).
55///
56/// 6: added [`Task::resume_override`] (a field only; `#[serde(default)]`, so
57/// an older record reads as `None` and [`read_path`] still accepts it).
58///
59/// 5: added [`Task::triage_applied`], the ids of triage questions whose
60/// answer has already been applied to this task. A "resume" answer used to
61/// leave no trace ([`Task::release`] clears [`Task::hold_reason`], which was
62/// the only place the applied marker lived), so when the released task failed
63/// its attempts and went back to `held`, the next idle pass found the same
64/// answered question "not applied" and released it again with `attempts` reset
65/// to 0 - the `max_attempts` bound never held. `#[serde(default)]` so an older
66/// record reads as empty. A task already looping when this build arrives has
67/// no record, so it is released once more, recorded, and then stays held.
68///
69/// 8: added [`Task::followup`], the origin of a task `crate::followup` filed
70/// from a merged run's leftover findings. Field-only bump, `#[serde(default)]`.
71///
72/// 4: added [`Task::blocked_from`], the status a task had the moment it
73/// became [`TaskStatus::Blocked`], so [`Task::unblock`] restores it instead
74/// of always landing on [`TaskStatus::Queued`]. Without it, a task a human
75/// or `crate::triage` had deliberately left [`TaskStatus::Held`] — machine
76/// or manual — would lose that the instant `crate::conduct` blocked it on a
77/// follow-up question, and come back `Queued` the moment the question was
78/// answered, regardless of what the answer said: exactly the loop where a
79/// task the operator told to stay held instead re-enters the competition
80/// queue every time someone answers a question about it. `#[serde(default)]`
81/// so an older record reads as `None`; [`Task::unblock`] then falls back to
82/// inferring `Held` from surviving hold evidence ([`Task::hold_reason`] /
83/// [`Task::hold_source`], never cleared by [`Task::block`]) rather than
84/// guessing `Queued` outright — see [`Task::unblock`]'s own doc.
85///
86/// 9: added [`Task::held_at`], the start of the current hold, so a notice can
87/// tell a question filed for this hold from one about an older cause.
88/// Field-only, `#[serde(default)]`.
89///
90/// 10: added [`Task::overrides`] and [`Task::review_of`], so a run started by
91/// hand (`magi run` / `magi review`) is carried by a task without losing its
92/// command-line choices. Field-only.
93///
94/// 11: added [`TaskStatus::Parked`] and [`Task::park_reason`], so a run that
95/// stopped at a node boundary (an upgrade, an operator's park) is no longer
96/// recorded as a failed task. Variant plus `#[serde(default)]` field; an older
97/// build must not half-read the new status.
98///
99/// 12: added [`Task::origin_chat`], the talk a task descends from, so a
100/// follow-up still knows its chat after an ancestor task is deleted.
101/// Field-only, `#[serde(default)]`.
102///
103/// 13: added [`Task::chat_notice`], the record that a chat-filed task's final
104/// state was reported to its conversation. Field-only, `#[serde(default)]`;
105/// a record below this schema is never notified (an upgrade must not replay
106/// the whole history into chats).
107///
108/// 3: added [`HoldSource`] so conductor recovery cannot release a hold an
109/// operator deliberately placed. Old records default to `None` and are
110/// protected as operator-held until an explicit release; the safe direction
111/// when their author was never recorded.
112///
113/// 2: added [`TaskStatus::Blocked`], [`Task::blocked_by`] and
114/// [`Task::block_reason`] (`crate::conduct`'s decisions) and
115/// [`Task::answers`] (operator answers carried forward to the next
116/// conductor prompt and the next run's instruction). All three are
117/// `#[serde(default)]`, so [`read_path`] accepts anything up to and
118/// including this schema rather than only an exact match — a task written
119/// by a build that only knew about schema 1 has nothing to say about
120/// blocking or answers, and defaulting those fields is exactly as good a
121/// reading as a value that build never had a chance to write.
122///
123/// 15: added [`Task::passes`], what each settled pass over a run did to the
124/// attempt budget and why it stopped. Field-only, `#[serde(default)]`; a task
125/// from before this has no entry for its earlier passes, which stay unknown.
126///
127/// 14: record whether a task count edit's overrides inherit daemon options.
128/// Old overrides default to isolated command-line settings, including empty ones.
129///
130/// 16: added [`Task::attempt_limit`], an optional task-specific retry budget.
131/// Field-only, `#[serde(default)]`; old records inherit the daemon limit.
132///
133/// 19: persist settled pass start times for upgrade-resume scheduling.
134/// Old passes default to unknown and use settlement order as an approximation.
135/// 20: persist the task decision chat destination, defaulting to absent.
136/// 21: repository assignment history and execution boundaries, empty on old tasks.
137pub const SCHEMA: u32 = 21;
138
139/// Candidate order only: all claims, lanes and eligibility gates still apply.
140/// Upgrade-parked runs retain their pass-start order ahead of ordinary work,
141/// regardless of ordinary priority. Old records without a start time use
142/// settlement time and task id as an approximation. Other parks are ordinary.
143/// Urgent slots and explicit interrupts are handled separately by the daemon.
144pub(crate) fn dispatch_order(a: &Task, b: &Task) -> std::cmp::Ordering {
145    match (a.upgrade_resume_key(), b.upgrade_resume_key()) {
146        (Some(a), Some(b)) => a.cmp(&b),
147        (Some(_), None) => std::cmp::Ordering::Less,
148        (None, Some(_)) => std::cmp::Ordering::Greater,
149        (None, None) => b.priority.cmp(&a.priority).then(a.id.cmp(&b.id)),
150    }
151}
152
153/// Who placed the current hold.
154#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
155#[serde(rename_all = "lowercase")]
156pub enum HoldSource {
157    /// An operator used the CLI or web UI.
158    Manual,
159    /// The daemon or conductor placed the hold as part of its own recovery.
160    Machine,
161}
162
163impl HoldSource {
164    /// Short human-facing label for reports and the CLI.
165    pub fn label(self) -> &'static str {
166        match self {
167            Self::Manual => "manual",
168            Self::Machine => "machine",
169        }
170    }
171}
172
173/// Where a task came from. Recorded because "who asked for this" is the first
174/// question about an autonomous run, and the answer is not recoverable later.
175#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
176#[serde(tag = "kind", rename_all = "lowercase")]
177pub enum Source {
178    /// A person, at a terminal or through the web UI.
179    Human,
180    /// An agent inside a run, via `magi task add`. Both ids are recorded so a
181    /// task can be traced back to the exact seat that asked for it.
182    Agent {
183        /// Run the asking agent belonged to.
184        run: String,
185        /// Node it was working in, e.g. `implement` or `review`.
186        node: String,
187    },
188    /// A GitHub issue, imported by number.
189    Issue {
190        /// Issue number.
191        number: u64,
192        /// `owner/repo`, as `gh` reports it.
193        repo: String,
194    },
195}
196
197/// The `node` a [`Source::Agent`] carries when the asker is a chat
198/// conversation (its `run` is then the conversation's id).
199pub const CHAT_NODE: &str = "chat";
200
201impl Source {
202    /// Short human-facing label, for lists and the web UI.
203    pub fn label(&self) -> String {
204        match self {
205            Self::Human => "human".to_owned(),
206            Self::Agent { run, node } => format!("{node}@{}", short(run)),
207            Self::Issue { number, .. } => format!("issue #{number}"),
208        }
209    }
210}
211
212/// Where a task is in its life.
213#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
214#[serde(rename_all = "lowercase")]
215pub enum TaskStatus {
216    /// Waiting to be claimed.
217    Queued,
218    /// Claimed by a daemon; a run is in flight.
219    Running,
220    /// A run finished and its gate passed.
221    Done,
222    /// A run finished without passing, and attempts remain.
223    Failed,
224    /// Out of attempts, or held by hand. The loop will not pick it up.
225    Held,
226    /// Waiting on another task or an unanswered question. See
227    /// [`Task::blocked_by`]. Set and cleared by `crate::conduct` and
228    /// `crate::daemon`'s deterministic resolver, never by hand.
229    Blocked,
230    /// The run stopped at a node boundary because the process was asked to
231    /// give itself back. Nothing failed: the run's work is intact and the next
232    /// loop resumes it. Runnable like [`TaskStatus::Queued`]; the reason is in
233    /// [`Task::park_reason`], never [`Task::last_error`].
234    Parked,
235}
236
237impl TaskStatus {
238    /// Is this task eligible for a daemon to claim?
239    pub fn runnable(self) -> bool {
240        matches!(self, Self::Queued | Self::Failed | Self::Parked)
241    }
242
243    /// Lowercase name, as it appears on disk and in the API.
244    pub fn as_str(self) -> &'static str {
245        match self {
246            Self::Queued => "queued",
247            Self::Running => "running",
248            Self::Done => "done",
249            Self::Failed => "failed",
250            Self::Held => "held",
251            Self::Blocked => "blocked",
252            Self::Parked => "parked",
253        }
254    }
255}
256
257/// How many tasks sit in each [`TaskStatus`], for a dashboard tile — never a
258/// per-task view, so it carries no ids.
259#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
260pub struct TaskCounts {
261    /// Waiting to be claimed.
262    pub queued: usize,
263    /// Claimed; a run is in flight.
264    pub running: usize,
265    /// A run finished and its gate passed.
266    pub done: usize,
267    /// A run finished without passing, and attempts remain.
268    pub failed: usize,
269    /// Out of attempts, or held by hand.
270    pub held: usize,
271    /// Waiting on another task or an unanswered question.
272    pub blocked: usize,
273    /// Run parked at a node boundary; resumable, not a failure.
274    pub parked: usize,
275}
276
277impl TaskCounts {
278    /// Tally `tasks` by status. A pure function over whatever [`Queue::list`]
279    /// already read, so it needs no root of its own and stays trivially
280    /// testable against a hand-built slice.
281    pub fn of(tasks: &[Task]) -> Self {
282        Self::of_statuses(tasks.iter().map(|task| task.status))
283    }
284
285    /// Count current statuses from a reconciled display projection.
286    pub(crate) fn of_statuses(statuses: impl IntoIterator<Item = TaskStatus>) -> Self {
287        let mut counts = Self::default();
288        for status in statuses {
289            match status {
290                TaskStatus::Queued => counts.queued += 1,
291                TaskStatus::Running => counts.running += 1,
292                TaskStatus::Done => counts.done += 1,
293                TaskStatus::Failed => counts.failed += 1,
294                TaskStatus::Held => counts.held += 1,
295                TaskStatus::Blocked => counts.blocked += 1,
296                TaskStatus::Parked => counts.parked += 1,
297            }
298        }
299        counts
300    }
301}
302
303/// Audit record and execution boundary for a repository reassignment.
304#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
305pub struct Reassignment {
306    /// Original repository.
307    pub from: PathBuf,
308    /// Newly selected repository.
309    pub to: PathBuf,
310    /// Control surface or conversation that requested this change.
311    pub actor: String,
312    /// Time of the operator decision.
313    pub at: Timestamp,
314    /// Runs before this boundary can never execute for this assignment.
315    pub run_boundary: usize,
316}
317
318/// One unit of work.
319#[derive(Debug, Clone, Serialize, Deserialize)]
320#[serde(deny_unknown_fields)]
321pub struct Task {
322    /// On-disk format version.
323    pub schema: u32,
324    /// Task id, e.g. `20260902-140501-a1b2`.
325    pub id: String,
326    /// One line, for lists and notifications.
327    pub title: String,
328    /// The task itself, handed to the graph verbatim.
329    pub instruction: String,
330    /// Explicit, SHA-pinned implementation imports; separate from instruction text.
331    #[serde(default, skip_serializing_if = "crate::refs::Sources::is_empty")]
332    pub sources: crate::refs::Sources,
333    /// Repository to work in.
334    pub repo: PathBuf,
335    /// Repository assignment boundaries; historical runs remain in `runs`.
336    #[serde(default)]
337    pub reassignments: Vec<Reassignment>,
338    /// Who asked.
339    pub source: Source,
340    /// Durable destination for task decision messages (including tasks filed outside chat).
341    #[serde(default)]
342    pub chat: Option<String>,
343    /// Higher runs first; ties break oldest-first so nothing starves.
344    #[serde(default)]
345    pub priority: i32,
346    /// Run this task alone: one implementer, no panel of judges to convince.
347    ///
348    /// `#[serde(default)]` so a queue file written before this field existed
349    /// still reads, as `false` - the ordinary multi-candidate competition,
350    /// unchanged. A task set to `solo` still runs the whole graph; only the
351    /// candidate count the daemon builds it with changes, and
352    /// [`crate::graph::Runner`] already collapses a single-candidate run to
353    /// implement → review → gate → merge on its own (see
354    /// [`crate::graph::Runner::review`]'s doc), so nothing about judging,
355    /// deliberation or voting had to change to support this.
356    #[serde(default)]
357    pub solo: bool,
358    /// Current state.
359    pub status: TaskStatus,
360    /// How many times this task has been claimed.
361    #[serde(default)]
362    pub attempts: usize,
363    /// Total attempt budget; `None` inherits the daemon limit.
364    #[serde(default)]
365    pub attempt_limit: Option<NonZeroUsize>,
366    /// Distinct runs, ordered by their most recent claim. Older records may
367    /// contain repeated ids; execution history lives in the run pass records.
368    #[serde(default)]
369    pub runs: Vec<String>,
370    /// Reserved startups that failed before execution; never a resume source or execution attempt.
371    #[serde(default)]
372    pub startup_failures: Vec<crate::run::StartupFailure>,
373    /// Why the last attempt did not land.
374    #[serde(default)]
375    pub last_error: Option<String>,
376    /// What a human hold is waiting on.
377    ///
378    /// `None` covers both the ordinary cases: a hold the loop makes itself
379    /// (out of attempts, or the disk gate closed) explains itself through
380    /// [`Task::last_error`] instead, and a human hold nobody bothered to
381    /// explain is still a valid hold. The queue has no way to express a
382    /// dependency between two tasks, so on the occasions a hold really is
383    /// "wait for that other task first", this is the only place that reason
384    /// survives - see [`Task::hold_manual`] and [`Task::release`].
385    ///
386    /// `#[serde(default)]` so a queue file written before this field existed
387    /// still reads, with no reason recorded rather than a parse error.
388    #[serde(default)]
389    pub hold_reason: Option<String>,
390    /// Who placed [`Task::hold_reason`].  `None` is a compatible old record;
391    /// see [`Task::operator_held`] for its deliberately conservative meaning.
392    #[serde(default)]
393    pub hold_source: Option<HoldSource>,
394    /// Diagnostic detail excerpted from the run that led to a hold - what a
395    /// human would have found opening `artifacts/` by hand, not the one-line
396    /// reason in [`Task::last_error`]. Set only when a run's own attempts are
397    /// exhausted and the task becomes [`TaskStatus::Held`]; `daemon` computes
398    /// it from the run's own record, since this module has no notion of a
399    /// run's internals. Bounded in length by the writer - see
400    /// `daemon::diagnostic` - so a verbose run cannot make this file grow
401    /// without limit.
402    ///
403    /// `#[serde(default)]` so a queue file written before this field existed
404    /// still reads, with no diagnostic recorded rather than a parse error.
405    #[serde(default)]
406    pub diagnostic: Option<String>,
407    /// What this task is waiting on: other task ids, unanswered
408    /// `crate::ask::Question` ids, or both. Non-empty exactly when
409    /// [`TaskStatus::Blocked`]; emptying it — see [`Task::unblock`] — is what
410    /// puts the task back at [`TaskStatus::Queued`].
411    ///
412    /// Set by `crate::conduct`'s decisions and cleared deterministically by
413    /// `crate::daemon` as each dependency resolves, never by a person. Never
414    /// `#[serde(default)]` is skipped: a queue file from before this field
415    /// existed has nothing to report here, and an empty list is exactly that.
416    #[serde(default)]
417    pub blocked_by: Vec<String>,
418    /// One line explaining the current [`Task::blocked_by`], written by
419    /// `crate::conduct`. Cleared whenever `blocked_by` empties.
420    #[serde(default)]
421    pub block_reason: Option<String>,
422    /// The status this task had the moment [`Task::block`] most recently
423    /// moved it to [`TaskStatus::Blocked`] — what [`Task::unblock`] restores
424    /// once nothing is left in `blocked_by`, instead of always landing on
425    /// [`TaskStatus::Queued`]. See [`SCHEMA`]'s doc for schema 4 on why this
426    /// exists: an answer to a question `crate::conduct` filed about a
427    /// [`TaskStatus::Held`] task must not itself be what puts the task back
428    /// in the competition queue.
429    ///
430    /// `#[serde(default)]` so a queue file written before this field existed
431    /// reads as `None`; [`Task::unblock`] treats that the same as a task
432    /// blocked straight from `Queued`, unless surviving hold evidence says
433    /// otherwise.
434    #[serde(default)]
435    pub blocked_from: Option<TaskStatus>,
436    /// Last change of blocking targets, independent of explanation or delivery writes.
437    #[serde(default)]
438    pub blocked_at: Option<Timestamp>,
439    /// Questions `crate::conduct` asked about this task that the operator has
440    /// since answered, oldest first — what was asked, and what they said.
441    ///
442    /// A blocking question's id leaves [`Task::blocked_by`] the moment
443    /// [`crate::ask::QuestionStatus::Answered`] is observed, but the id alone
444    /// tells nobody what was decided. This is what carries the answer's
445    /// *content* forward: into the next conductor prompt for this task, and
446    /// into the instruction handed to the next run — see `crate::daemon`'s
447    /// deterministic blocker resolution. Kept for the task's whole life, the
448    /// same as [`Task::runs`]: a release resets attempts, not evidence.
449    #[serde(default)]
450    pub answers: Vec<AnsweredQuestion>,
451    /// Ids of the `crate::triage` questions whose answer has been applied to
452    /// this task. Unlike [`Task::hold_reason`], [`Task::release`] and every
453    /// hold transition leave it alone, so an answer is applied at most once
454    /// however many times the task is held again. See [`SCHEMA`]'s doc for
455    /// schema 5. `#[serde(default)]` so an older record reads as empty.
456    #[serde(default)]
457    pub triage_applied: Vec<String>,
458    /// Ids of the `magi ask` questions whose [`crate::ask::ChoiceAction`] has
459    /// been applied to this task. Separate from [`Task::triage_applied`]
460    /// (a different producer) and, like it, untouched by [`Task::release`],
461    /// so one answer acts at most once however often the task is held again.
462    /// `#[serde(default)]` so an older record reads as empty.
463    #[serde(default)]
464    pub actions_applied: Vec<String>,
465    /// Exact task/chat commands committed in the same write as their effects.
466    /// These receipts survive subsequent transitions and execution starts.
467    #[serde(default, skip_serializing_if = "std::collections::BTreeMap::is_empty")]
468    pub decision_effects: std::collections::BTreeMap<String, String>,
469    /// Exact resume pins explicitly replaced or removed before dispatch.
470    /// Retained independently of later task transitions and stale writers.
471    #[serde(default, skip_serializing_if = "std::collections::BTreeMap::is_empty")]
472    pub superseded_resumes: std::collections::BTreeMap<String, String>,
473    /// Resume inquiry ownership committed atomically with task dispatch.
474    /// This is not effect evidence: only the run's committed pass proves execution.
475    /// Retained across recovery and stale writers until that pass can consume it.
476    #[serde(default, skip_serializing_if = "std::collections::BTreeMap::is_empty")]
477    pub dispatched_resumes: std::collections::BTreeMap<String, String>,
478    /// Durable base-recovery request keys saved atomically with the exact-run pin.
479    #[serde(default)]
480    pub base_recovery_requests: Vec<String>,
481    /// The operator's "resume" answer to a triage question, kept until the
482    /// task actually runs (or is done) so `crate::conduct` cannot silently
483    /// undo it and `crate::triage` can tell that a hold it sees now came
484    /// *after* the answer. See [`OperatorResume`]. `#[serde(default)]`.
485    #[serde(default)]
486    pub resume_override: Option<OperatorResume>,
487    /// Immutable repair receipts, saved atomically with the exact-run queue pin.
488    #[serde(default)]
489    pub repair_grants: Vec<crate::repair_budget::Receipt>,
490    /// Append-only owner-authorized reconciliation of an unspent receipt.
491    #[serde(default)]
492    pub repair_reconciliations: Vec<crate::repair_budget::reconcile::Receipt>,
493    /// Latest explicit operator release. Historical answers remain audit evidence;
494    /// this approval takes precedence over their earlier waiting premises.
495    #[serde(default)]
496    pub resumption: Option<Resumption>,
497    /// Earlier explicit approvals retained for audit and instruction suffix matching.
498    #[serde(default)]
499    pub resumption_history: Vec<Resumption>,
500    /// Latest explicit release or manual hold, used to reject delayed answers.
501    #[serde(default)]
502    pub operator_decided_at: Option<Timestamp>,
503    /// Set by `crate::conduct` when it chooses `Review` recovery for a task
504    /// whose branch survived a blocked run: the branch to reopen with
505    /// `crate::graph::Runner::review` instead of competing from scratch.
506    ///
507    /// Requeues the task the same way [`Task::release`] does, so it is
508    /// picked up by the ordinary loop; `crate::daemon` reads this field once,
509    /// when it actually starts the run, and clears it either way — consumed
510    /// on success, dropped if the branch no longer exists by then. Never set
511    /// from the conductor's own words: `crate::daemon` derives the branch
512    /// name itself from the task's last run, so a hallucinated branch can
513    /// never reach here.
514    #[serde(default)]
515    pub review_branch: Option<String>,
516    /// Authored criteria when the retained recovery review was selected.
517    #[serde(default)]
518    pub review_instruction: Option<String>,
519    /// Explicit public implementation selected by the operator; never inferred from prose.
520    #[serde(default)]
521    pub pr_recovery: Option<crate::pr_recovery::Selection>,
522    /// A release deliberately starts a new competition instead of resuming
523    /// the prior run. History remains as evidence in `runs`.
524    #[serde(default)]
525    pub fresh_start: bool,
526    /// Explicit replacement selection; persists through dispatch and resume.
527    #[serde(default)]
528    pub replacement: Option<crate::merge_decision::Replacement>,
529    /// Marked by an operator (`magi task interrupt`) to ask `magi serve` to
530    /// run this one ahead of whatever it already has in flight, once
531    /// `[daemon] pause_for_interrupts` is on - see
532    /// `crate::daemon::advance_interrupt`. Never set by the loop itself, and
533    /// deliberately a different operation from [`Task::set_priority`]: a
534    /// priority only reorders the queue a claim has not reached yet, while
535    /// this asks a run already in flight to park at its next safe boundary
536    /// and step aside. `#[serde(default)]` so a queue file written before
537    /// this field existed still reads, as `false` - no task interrupts
538    /// anything unless asked to, exactly as before.
539    #[serde(default)]
540    pub interrupt: bool,
541    /// Marked by `magi task add --urgent` or `magi task urgent`.
542    /// `crate::daemon::poll` dispatches this task through its own one-slot `urgent_sem` the moment it is
543    /// runnable, in addition to whatever is already running under the
544    /// ordinary `[daemon] max_concurrent_runs` pool - never instead of it,
545    /// and never by pausing or otherwise touching that run. This is the
546    /// opposite direction from [`Task::interrupt`]: that one asks a run
547    /// already in flight to step aside; this one never asks anything to
548    /// step aside, it only spends one additional, temporary concurrency
549    /// slot. The two are independent and may both be set on the same task,
550    /// but this exemption stops at `[daemon] pause_for_interrupts`'s own
551    /// park/resume handoff (75dd): while an interrupt sequence is actively
552    /// parking, running, or resuming - its own, or an unrelated task's -
553    /// `crate::daemon::interrupt_gate` withholds an urgent candidate exactly
554    /// like an ordinary one, never exempted. 75dd's "at most one run, ever,
555    /// at once" guarantee takes precedence, because the alternative is a run
556    /// still genuinely in flight (only *asked* to park, not yet gone) ending
557    /// up alongside a second one this feature let through - the very thing
558    /// that guarantee exists to rule out.
559    ///
560    /// `#[serde(default)]` so a queue file written before this field existed
561    /// still reads, as `false` - no task claims the urgent slot unless asked
562    /// to, exactly as before.
563    #[serde(default)]
564    pub urgent: bool,
565    /// Set by [`Task::new`], cleared once a queue has stored the task. Never
566    /// persisted: a task read from disk is always an existing one. While set,
567    /// [`Queue::put`] reserves the id (see [`Queue::file_with`]) instead of
568    /// merging into whatever record already carries it.
569    #[serde(skip)]
570    pub(crate) unfiled: bool,
571    /// Files (typically screenshots) copied into `<id>.attachments/` beside
572    /// this task's file by [`Queue::attach`], as bare validated names. The
573    /// copy is what makes them reach the implementer: the original may be
574    /// cleaned up long before the task runs. Untouched by [`Task::edit`].
575    /// `#[serde(default)]` so an older record reads as empty.
576    #[serde(default)]
577    pub attachments: Vec<String>,
578    /// Set on a task `crate::followup` filed from the findings a merged run
579    /// left open: which run and findings it carries, and how many follow-ups
580    /// deep it is. `None` for every ordinary task. `#[serde(default)]`.
581    #[serde(default)]
582    pub followup: Option<FollowUp>,
583    /// Id of the chat this task descends from: set by [`Task::new`] when a
584    /// chat files it, inherited by the follow-ups `crate::followup` files, so
585    /// the provenance survives deleting an ancestor. `None` for a task written
586    /// before the field existed (`crate::consult` then walks the ancestry).
587    /// `#[serde(default)]`.
588    #[serde(default)]
589    pub origin_chat: Option<String>,
590    /// The command-line choices (`--merge`, `-c`, `--seed`, ...) of the
591    /// `magi run` / `magi review` that filed this task, applied on top of the
592    /// repository's config by whoever executes it - a daemon included - so
593    /// handing the task over does not change what it does. A count edit on an
594    /// ordinary queue task explicitly inherits daemon options instead.
595    /// `#[serde(default)]`.
596    #[serde(default)]
597    pub overrides: Option<RunOverrides>,
598    /// The branch an explicit `magi review <branch>` asked to review. Unlike
599    /// [`Task::review_branch`] (a recovery choice the daemon consumes and
600    /// drops back to a competition when the branch is gone), this is the whole
601    /// request: it is never consumed, and a missing branch fails the attempt
602    /// rather than paying for an implementation nobody asked for.
603    /// `#[serde(default)]`.
604    #[serde(default)]
605    pub review_of: Option<String>,
606    /// When the current hold began. Set by the transitions into
607    /// [`TaskStatus::Held`] (a re-hold keeps it), cleared by
608    /// [`Task::release`]. `crate::notices` uses it as the identity of the
609    /// cause: a question filed before it is about something older.
610    #[serde(default)]
611    pub held_at: Option<Timestamp>,
612    /// Why the run parked, while the task is [`TaskStatus::Parked`]. Kept apart
613    /// from [`Task::last_error`] because nothing failed. Cleared by every
614    /// transition out of the parked state. `#[serde(default)]`.
615    #[serde(default)]
616    pub park_reason: Option<String>,
617    /// The last final state reported to the originating chat. See
618    /// [`Task::chat_notice_due`]. Never cleared by a release or requeue.
619    #[serde(default)]
620    pub chat_notice: Option<ChatNotice>,
621    /// Delivery ledger, unioned under the task lock even on stale writes.
622    #[serde(default)]
623    pub chat_notices: Vec<String>,
624    /// Structured producer identity of the unresolved hold. Requeues and prose
625    /// updates retain it; a settled run or a distinct startup stage replaces it.
626    #[serde(default)]
627    pub hold_notice_cause: Option<NoticeCause>,
628    /// Append-only: one entry per pass over a run that the loop settled. A
629    /// resumed run is one run with several passes, and `attempts` counts
630    /// claims net of refunds, so the two are not the same number; this says
631    /// which pass cost what. Kept across a release.
632    #[serde(default)]
633    pub passes: Vec<TaskPass>,
634    /// When the loop claimed this task for its latest dispatch. Stamped under
635    /// the claim, before any slow start-up work, so it is the real dispatch
636    /// order; `record_pass_at` prefers it over the graph's own pass start.
637    #[serde(default)]
638    pub dispatched_at: Option<Timestamp>,
639    /// Durable failed-input budget, unaffected by automatic release/requeue.
640    #[serde(default)]
641    pub recovery_budget: Option<RecoveryBudget>,
642    /// Inputs resolved before starting the current automatic attempt. The
643    /// settlement uses this same identity even for review-only runs.
644    #[serde(default)]
645    pub recovery_admission: Option<RecoveryAdmission>,
646    /// Previously seen input generations. Switching inputs away and back does
647    /// not refund an exhausted generation without explicit operator authority.
648    #[serde(default)]
649    pub recovery_generations: Vec<RecoveryBudget>,
650    /// When the task was filed.
651    pub created_at: Timestamp,
652    /// Last change to this file.
653    pub updated_at: Timestamp,
654}
655
656/// Admission identity shared by start and settlement.
657#[derive(Debug, Clone, Serialize, Deserialize)]
658pub struct RecoveryAdmission {
659    /// Fetched upstream commit before any run-local rebase.
660    pub base: String,
661    /// Resolved instruction references and explicit review source.
662    pub inputs: String,
663}
664
665/// Failures against one recovery input generation. An owner release explicitly
666/// starts a new generation; a machine requeue never replenishes it.
667#[derive(Debug, Clone, Serialize, Deserialize)]
668pub struct RecoveryBudget {
669    /// Authored instructions, not generated review scaffolding.
670    pub instruction: String,
671    /// Upstream commit used to prepare this generation.
672    pub base: String,
673    /// Referenced input commits, including their resolved identities.
674    pub inputs: String,
675    /// Stable processing stage of the last failure.
676    pub stage: String,
677    /// Failed passes, independent of the resettable claim counter.
678    pub failures: usize,
679    /// Fingerprint of actual candidate patches; equivalent rebased commits do
680    /// not count as progress. Unknown inputs never replenish the budget.
681    #[serde(default)]
682    pub progress: Option<String>,
683}
684
685fn recovery_progress(state: &crate::run::RunState) -> Option<String> {
686    use crate::proc::Quiet as _;
687    use std::hash::{Hash, Hasher};
688    let mut patches = Vec::new();
689    for candidate in state.candidates.iter().filter(|c| c.commits > 0) {
690        let output = std::process::Command::new("git")
691            .current_dir(&state.repo)
692            .args(["diff", "--binary", &state.base_commit, &candidate.branch])
693            .quiet()
694            .output()
695            .ok()?;
696        if !output.status.success() {
697            return None;
698        }
699        patches.push(output.stdout);
700    }
701    patches.sort();
702    patches.dedup();
703    let mut hash = std::collections::hash_map::DefaultHasher::new();
704    patches.hash(&mut hash);
705    Some(format!("{:x}", hash.finish()))
706}
707
708/// The implementation inputs a recovery budget is keyed on: the explicit,
709/// SHA-pinned sources only, never references parsed from instruction prose.
710/// No sources is `[]`, the key an input-free task always had.
711pub(crate) fn recovery_inputs(sources: &crate::refs::Sources) -> String {
712    serde_json::to_string(
713        &sources
714            .start_from
715            .iter()
716            .map(|i| ("start", &i.token, &i.sha))
717            .chain(
718                sources
719                    .pick_commits
720                    .iter()
721                    .map(|i| ("pick", &i.token, &i.sha)),
722            )
723            .collect::<Vec<_>>(),
724    )
725    .unwrap_or_default()
726}
727
728/// Facts a producer can independently attest about a held outcome.
729#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
730pub struct NoticeCause {
731    /// Processing stage or verified external evidence.
732    pub stage: String,
733    /// Producer-verified blocker object, independent of the displayed error.
734    /// Omitted when absent to preserve existing persisted notice keys.
735    #[serde(default, skip_serializing_if = "Option::is_none")]
736    pub target: Option<String>,
737    /// An actual run that reached settlement; absent for preflight failures.
738    pub run: Option<String>,
739    /// The settled pass, so a resumed run can report a new failure.
740    pub pass: Option<usize>,
741}
742
743/// Current and legacy completion keys; legacy run counts contain only digits.
744pub(crate) fn is_done_notice_key(key: &str) -> bool {
745    key == "done"
746        || key
747            .strip_prefix("done#")
748            .is_some_and(|count| !count.is_empty() && count.bytes().all(|b| b.is_ascii_digit()))
749}
750
751/// What a settled pass did to the attempt budget.
752#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
753#[serde(rename_all = "snake_case")]
754pub enum PassCost {
755    /// The attempt stays counted.
756    Spent,
757    /// The attempt was handed back.
758    Refunded,
759}
760
761/// One settled pass over a run. See [`Task::passes`].
762#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
763pub struct TaskPass {
764    /// The run the pass belongs to.
765    pub run: String,
766    /// [`crate::run::RunPass::index`] in that run.
767    pub pass_index: usize,
768    /// What it did to the budget.
769    pub cost: PassCost,
770    /// `attempts` once this pass was settled.
771    pub attempts_after: usize,
772    /// When this pass began, retained across daemon upgrades.
773    #[serde(default)]
774    pub started_at: Option<Timestamp>,
775    /// When the loop settled it.
776    pub settled_at: Timestamp,
777    /// Why the pass parked, when it did.
778    #[serde(default)]
779    pub parked: Option<crate::run::ParkCause>,
780}
781
782/// What became of a completion notice. See [`Task::chat_notice`].
783#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
784#[serde(rename_all = "lowercase")]
785pub enum ChatNoticeOutcome {
786    /// Queued as a draft of the originating talk.
787    Posted,
788    /// The talk is gone or closed; nothing was queued, and nothing will be.
789    Skipped,
790}
791
792/// The final state of a chat-filed task that was already reported (or skipped).
793#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
794pub struct ChatNotice {
795    /// Identity of the cause, see [`Task::chat_notice_key`].
796    pub key: String,
797    /// When it was recorded.
798    pub at: Timestamp,
799    /// Posted or skipped.
800    pub outcome: ChatNoticeOutcome,
801}
802
803/// Command-line choices carried by a task. See [`Task::overrides`].
804#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
805pub struct RunOverrides {
806    /// Count edits on ordinary queued tasks inherit the loop's config and merge.
807    /// False for direct-run overrides and old records, even when otherwise empty.
808    #[serde(default)]
809    pub inherit_daemon_options: bool,
810    /// `--merge`: `none`, `local` or `pr`.
811    #[serde(default)]
812    pub merge: Option<String>,
813    /// `-c` / `--implementers`: parallel implementations (persisted as `candidates`).
814    #[serde(default)]
815    pub candidates: Option<usize>,
816    /// `-j`: independent judges.
817    #[serde(default)]
818    pub judges: Option<usize>,
819    /// `--reviewers`: reviewers per round.
820    #[serde(default)]
821    pub reviewers: Option<usize>,
822    /// `--review-rounds`.
823    #[serde(default)]
824    pub review_rounds: Option<usize>,
825    /// `--seed`.
826    #[serde(default)]
827    pub seed: Option<u64>,
828    /// `--config`, absolute: the daemon's own working directory differs.
829    #[serde(default)]
830    pub config: Option<PathBuf>,
831}
832
833impl RunOverrides {
834    /// Lay `other` over these: every choice `other` made wins, the rest stay.
835    pub fn merge_over(&mut self, other: &RunOverrides) {
836        macro_rules! take {
837            ($($f:ident),*) => {$(
838                if other.$f.is_some() {
839                    self.$f.clone_from(&other.$f);
840                }
841            )*};
842        }
843        take!(
844            merge,
845            candidates,
846            judges,
847            reviewers,
848            review_rounds,
849            seed,
850            config
851        );
852    }
853
854    /// Apply these on top of `config`.
855    pub fn apply(&self, config: &mut crate::config::Config) {
856        if let Some(n) = self.candidates {
857            config.graph.implementers = n;
858        }
859        if let Some(n) = self.judges {
860            config.graph.judges = n;
861        }
862        if let Some(n) = self.reviewers {
863            config.graph.reviewers = n;
864        }
865        if let Some(n) = self.review_rounds {
866            config.graph.review_rounds = n;
867        }
868        if let Some(m) = &self.merge
869            && let Ok(mode) = crate::daemon::merge_mode(m)
870        {
871            config.merge.mode = mode;
872        }
873        if let Some(s) = self.seed {
874            config.blind.seed = Some(s);
875        }
876    }
877}
878
879/// What a follow-up task came from. See [`Task::followup`].
880#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
881pub struct FollowUp {
882    /// The merged run whose open findings this task carries.
883    pub run: String,
884    /// The queue task that run served, when it had one.
885    #[serde(default)]
886    pub origin_task: Option<String>,
887    /// The merged pull request.
888    pub pr: String,
889    /// Ids of the findings (e.g. `R3-1-1`) this task covers.
890    pub findings: Vec<String>,
891    /// Follow-up depth: 1 for a follow-up of an ordinary task's run, 2 for a
892    /// follow-up of that, and so on. An ordinary task is generation 0.
893    pub generation: u32,
894}
895
896/// Durable scope of an explicit operator resumption, surviving run startup.
897#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
898pub struct Resumption {
899    /// Monotonic count of explicit resumptions.
900    pub generation: u64,
901    /// Mutation path that applied the approval.
902    pub source: String,
903    /// Answered question, if the approval came from one.
904    pub question_id: Option<String>,
905    /// When this approval was applied.
906    pub at: Timestamp,
907    /// Authored instruction approved at release.
908    pub instruction: String,
909    /// Number of historical answers superseded as waiting premises.
910    pub answers_through: usize,
911    /// Legacy run-list boundary retained for record compatibility. Evidence
912    /// uses approval time and run passes because resumes retain the same id.
913    pub runs_through: usize,
914    /// Previous hold or dependency reason cleared by this release.
915    pub cleared_reason: Option<String>,
916    /// Verified evidence versions already used to block after this approval.
917    #[serde(default)]
918    pub blocking_evidence: Vec<String>,
919}
920
921/// A triage "resume" answer and what became of it. See
922/// [`Task::resume_override`].
923#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
924pub struct OperatorResume {
925    /// 回答された Question の ID。Question を伴わない再開では空文字列。
926    pub question_id: String,
927    /// When the answer was applied.
928    pub at: Timestamp,
929    /// The reason `crate::conduct` gave for holding the task again after the
930    /// answer, if it did. The conductor may do this once.
931    #[serde(default)]
932    pub conductor_rehold: Option<String>,
933    /// The operator answered "resume" a second time, to the question about
934    /// that contradiction: the conductor may no longer hold this task.
935    #[serde(default)]
936    pub forced: bool,
937    /// Set when the answer was a structured `resume` action on a `magi ask`
938    /// choice ([`crate::ask::ChoiceAction::Resume`]): the run the operator
939    /// chose to continue. Its presence also stops `crate::conduct` from
940    /// requeuing the task into a fresh competition, which would discard
941    /// exactly the run that was named. Cleared with the rest of the record
942    /// once the task runs. `#[serde(default)]` so older records read as `None`.
943    #[serde(default)]
944    pub pinned_run: Option<String>,
945}
946
947/// One question `crate::conduct` asked about a task, and what the operator
948/// said back. See [`Task::answers`].
949#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
950pub struct AnsweredQuestion {
951    /// The question as asked, e.g. [`crate::ask::Question::summary`].
952    pub question: String,
953    /// What the operator answered.
954    pub answer: String,
955}
956
957impl Task {
958    /// File a new task. Persist it with [`Queue::put`].
959    pub fn new(title: String, instruction: String, repo: PathBuf, source: Source) -> Self {
960        let now = Timestamp::now();
961        let origin_chat = match &source {
962            Source::Agent { run, node } if node == CHAT_NODE => Some(run.clone()),
963            _ => None,
964        };
965        Self {
966            schema: SCHEMA,
967            id: new_id(),
968            title,
969            instruction,
970            sources: crate::refs::Sources::default(),
971            repo,
972            reassignments: Vec::new(),
973            source,
974            chat: None,
975            priority: 0,
976            solo: false,
977            status: TaskStatus::Queued,
978            attempts: 0,
979            attempt_limit: None,
980            runs: Vec::new(),
981            startup_failures: Vec::new(),
982            last_error: None,
983            hold_reason: None,
984            hold_source: None,
985            diagnostic: None,
986            blocked_by: Vec::new(),
987            block_reason: None,
988            blocked_from: None,
989            blocked_at: None,
990            answers: Vec::new(),
991            triage_applied: Vec::new(),
992            actions_applied: Vec::new(),
993            decision_effects: Default::default(),
994            superseded_resumes: Default::default(),
995            dispatched_resumes: Default::default(),
996            base_recovery_requests: Vec::new(),
997            resume_override: None,
998            repair_grants: Vec::new(),
999            repair_reconciliations: Vec::new(),
1000            resumption: None,
1001            resumption_history: Vec::new(),
1002            operator_decided_at: None,
1003            review_branch: None,
1004            review_instruction: None,
1005            pr_recovery: None,
1006            fresh_start: false,
1007            replacement: None,
1008            interrupt: false,
1009            urgent: false,
1010            unfiled: true,
1011            attachments: Vec::new(),
1012            followup: None,
1013            origin_chat,
1014            overrides: None,
1015            review_of: None,
1016            held_at: None,
1017            park_reason: None,
1018            chat_notice: None,
1019            chat_notices: Vec::new(),
1020            hold_notice_cause: None,
1021            passes: Vec::new(),
1022            dispatched_at: None,
1023            recovery_budget: None,
1024            recovery_admission: None,
1025            recovery_generations: Vec::new(),
1026            created_at: now,
1027            updated_at: now,
1028        }
1029    }
1030
1031    /// Apply a validated idle-task assignment, preserving evidence and history.
1032    pub(crate) fn reassign_repository(&mut self, repo: PathBuf, actor: &str) {
1033        self.stamp_schema();
1034        if matches!(self.status, TaskStatus::Failed | TaskStatus::Parked) {
1035            self.hold_manual(Some(
1036                "Repository reassigned; inspect history and release to start fresh.".into(),
1037            ));
1038        }
1039        let at = Timestamp::now();
1040        self.reassignments.push(Reassignment {
1041            from: self.repo.clone(),
1042            to: repo.clone(),
1043            actor: actor.to_owned(),
1044            at,
1045            run_boundary: self.runs.len(),
1046        });
1047        self.repo = repo;
1048        self.review_branch = None;
1049        self.review_instruction = None;
1050        self.pr_recovery = None;
1051        self.replacement = None;
1052        self.interrupt = false;
1053        self.resume_override = None;
1054        self.fresh_start = true;
1055        self.operator_decided_at = Some(at);
1056    }
1057
1058    /// Public branch for the task's current repository assignment.
1059    pub fn publication_branch(&self) -> String {
1060        crate::run::task_pr_branch_name(&self.id, self.reassignments.len())
1061    }
1062
1063    /// Runs eligible for execution in the current assignment only.
1064    pub fn execution_runs(&self) -> &[String] {
1065        let boundary = self.reassignments.last().map_or(0, |r| r.run_boundary);
1066        self.runs.get(boundary..).unwrap_or_default()
1067    }
1068
1069    /// Whether a historical run still belongs to this execution assignment.
1070    pub fn execution_run(&self, run: &str) -> bool {
1071        self.execution_runs().iter().any(|id| id == run)
1072    }
1073
1074    /// Check both the assignment boundary and the saved repository before execution.
1075    pub(crate) fn assignment_accepts(&self, run: &crate::run::RunState) -> bool {
1076        self.reassignments.last().is_none_or(|boundary| {
1077            self.execution_run(&run.id)
1078                && run.task_assignment == self.reassignments.len()
1079                && run.created_at > boundary.at
1080                && run
1081                    .repo
1082                    .canonicalize()
1083                    .ok()
1084                    .zip(self.repo.canonicalize().ok())
1085                    .is_some_and(|(run_repo, task_repo)| run_repo == task_repo)
1086        })
1087    }
1088
1089    /// Questions issued before reassignment cannot control the new assignment.
1090    pub(crate) fn stale_question(&self, q: &crate::ask::Question) -> bool {
1091        self.reassignments
1092            .last()
1093            .is_some_and(|r| q.asked_at <= r.at)
1094            || (self.runs.contains(&q.run) && !self.execution_run(&q.run))
1095    }
1096
1097    /// The chat this task itself says it came from, including its original source.
1098    pub fn chat_talk(&self) -> Option<&str> {
1099        if let Some(id) = &self.origin_chat {
1100            return Some(id);
1101        }
1102        match &self.source {
1103            Source::Agent { run, node } if node == CHAT_NODE => Some(run),
1104            _ => None,
1105        }
1106    }
1107
1108    /// The talk that filed this task *itself* (`Source::Agent` with
1109    /// [`CHAT_NODE`]); unlike [`Task::chat_talk`] a follow-up's inherited
1110    /// `origin_chat` does not count.
1111    pub fn filed_by_chat(&self) -> Option<&str> {
1112        match &self.source {
1113            Source::Agent { run, node } if node == CHAT_NODE => Some(run),
1114            _ => None,
1115        }
1116    }
1117
1118    /// Identity of a material outcome. Prose and wall-clock times are never
1119    /// evidence. Dependencies are a set; held causes survive intermediate states.
1120    pub fn chat_notice_key(&self) -> Option<String> {
1121        match self.status {
1122            TaskStatus::Done => Some("done".to_owned()),
1123            TaskStatus::Held => {
1124                let cause = self
1125                    .hold_notice_cause
1126                    .clone()
1127                    .unwrap_or_else(|| self.unresolved_hold_cause());
1128                Some(format!(
1129                    "cause:{}",
1130                    serde_json::to_string(&cause).expect("cause")
1131                ))
1132            }
1133            TaskStatus::Blocked => {
1134                let ids: std::collections::BTreeSet<_> = self.blocked_by.iter().collect();
1135                // Only new verified blocking evidence versions the dependency
1136                // set. Freezing an unrelated hold on release must not do so.
1137                let evidence = self
1138                    .hold_notice_cause
1139                    .as_ref()
1140                    .filter(|c| c.stage.starts_with("conductor-evidence:"));
1141                Some(format!(
1142                    "dependencies:{}",
1143                    serde_json::to_string(&(ids, evidence)).expect("ids")
1144                ))
1145            }
1146            _ => None,
1147        }
1148    }
1149
1150    fn unresolved_hold_cause(&self) -> NoticeCause {
1151        NoticeCause {
1152            stage: "hold".into(),
1153            target: None,
1154            run: self.runs.last().cloned(),
1155            pass: None,
1156        }
1157    }
1158
1159    /// Exact old delivery identity, only for reconciling an existing record.
1160    pub(crate) fn legacy_chat_notice_key(&self) -> Option<String> {
1161        let key = match self.status {
1162            TaskStatus::Held if self.hold_notice_cause.is_none() => Some(format!(
1163                "held#{}",
1164                self.held_at.map(|t| t.to_string()).unwrap_or_default()
1165            )),
1166            TaskStatus::Blocked => Some(format!(
1167                "blocked#{}#{}",
1168                self.blocked_by.join(","),
1169                self.block_reason.as_deref().unwrap_or_default()
1170            )),
1171            _ => None,
1172        };
1173        key.filter(|key| self.legacy_notice_matches(key))
1174    }
1175
1176    pub(crate) fn legacy_notice_matches(&self, key: &str) -> bool {
1177        match self.status {
1178            TaskStatus::Held if self.hold_notice_cause.is_none() => key
1179                .strip_prefix("held#")
1180                .is_some_and(|time| time.is_empty() || time.parse::<Timestamp>().is_ok()),
1181            TaskStatus::Blocked
1182                if self
1183                    .hold_notice_cause
1184                    .as_ref()
1185                    .is_none_or(|c| !c.stage.starts_with("conductor-evidence:")) =>
1186            {
1187                key.strip_prefix("blocked#").is_some_and(|tail| {
1188                    let Some((ids, _)) = tail.split_once('#') else {
1189                        return false;
1190                    };
1191                    let old: std::collections::BTreeSet<_> =
1192                        ids.split(',').filter(|id| !id.is_empty()).collect();
1193                    let current: std::collections::BTreeSet<_> =
1194                        self.blocked_by.iter().map(String::as_str).collect();
1195                    old == current
1196                })
1197            }
1198            _ => false,
1199        }
1200    }
1201
1202    fn import_chat_notice(&mut self) {
1203        if let Some(n) = &self.chat_notice {
1204            let key = if is_done_notice_key(&n.key) {
1205                "done".to_owned()
1206            } else if self.legacy_notice_matches(&n.key) {
1207                self.chat_notice_key().unwrap_or_else(|| n.key.clone())
1208            } else {
1209                n.key.clone()
1210            };
1211            if !self.chat_notices.contains(&key) {
1212                self.chat_notices.push(key);
1213            }
1214        }
1215    }
1216
1217    /// A producer records the processing stage and actual run/pass, never the
1218    /// error's rendered prose. No run means startup made no implementation progress.
1219    pub(crate) fn notice_cause(&mut self, stage: &str, run: Option<&str>, pass: Option<usize>) {
1220        self.import_chat_notice();
1221        self.hold_notice_cause = Some(NoticeCause {
1222            stage: stage.to_owned(),
1223            target: None,
1224            run: run.map(str::to_owned),
1225            pass,
1226        });
1227    }
1228
1229    /// Startup retries cannot replace an unresolved run outcome without doing
1230    /// work. Distinct startup stages can still explain a newly encountered blocker.
1231    pub(crate) fn startup_notice_cause(&mut self, stage: &str) {
1232        let recovery_only = matches!(
1233            stage,
1234            "startup-source" | "startup-candidates" | "startup-public-head"
1235        );
1236        match self.hold_notice_cause.as_ref() {
1237            Some(cause) if recovery_only && !cause.stage.starts_with("startup-") => return,
1238            None if recovery_only
1239                && self
1240                    .chat_notice
1241                    .as_ref()
1242                    .is_some_and(|n| !is_done_notice_key(&n.key)) =>
1243            {
1244                return;
1245            }
1246            _ => {}
1247        }
1248        self.notice_cause(stage, None, None);
1249    }
1250
1251    /// Apply a preflight failure without allowing Running's generic failure
1252    /// identity to overwrite the producer's stage or its unresolved recovery anchor.
1253    pub(crate) fn fail_startup(
1254        &mut self,
1255        stage: &str,
1256        why: impl Into<String>,
1257        max_attempts: usize,
1258    ) {
1259        let unresolved = self.hold_notice_cause.clone();
1260        self.fail(why, max_attempts);
1261        self.hold_notice_cause = unresolved;
1262        self.startup_notice_cause(stage);
1263    }
1264
1265    /// A startup failure tied to a concrete object, such as a missing attachment.
1266    pub(crate) fn fail_startup_target(
1267        &mut self,
1268        stage: &str,
1269        target: String,
1270        why: impl Into<String>,
1271        max_attempts: usize,
1272    ) {
1273        self.fail_startup(stage, why, max_attempts);
1274        if let Some(cause) = self.hold_notice_cause.as_mut() {
1275            cause.target = Some(target);
1276        }
1277    }
1278
1279    /// A chat-filed task owes each material final outcome at most one notice.
1280    pub fn chat_notice_due(&self) -> Option<String> {
1281        self.filed_by_chat()?;
1282        if self.schema < 13 {
1283            return None;
1284        }
1285        let key = self.chat_notice_key()?;
1286        if self.chat_notices.contains(&key) {
1287            return None;
1288        }
1289        match &self.chat_notice {
1290            Some(n)
1291                if n.key == key
1292                    || (key == "done" && is_done_notice_key(&n.key))
1293                    || self.legacy_notice_matches(&n.key) =>
1294            {
1295                None
1296            }
1297            _ => Some(key),
1298        }
1299    }
1300
1301    /// Short form used in reports, matching a run's short id.
1302    pub fn short(&self) -> &str {
1303        short(&self.id)
1304    }
1305
1306    /// Record that triage question `question_id`'s answer has been applied.
1307    pub fn mark_triage_applied(&mut self, question_id: &str) {
1308        if !self.triage_applied(question_id) {
1309            self.triage_applied.push(question_id.to_owned());
1310        }
1311    }
1312
1313    /// Has the action of `magi ask` question `question_id` already been
1314    /// applied, or is it being applied now? See [`Task::actions_applied`].
1315    pub fn action_applied(&self, question_id: &str) -> bool {
1316        self.actions_applied.iter().any(|id| id == question_id)
1317    }
1318
1319    /// Record that `magi ask` question `question_id`'s action was applied.
1320    pub fn mark_action_applied(&mut self, question_id: &str) {
1321        if !self.action_applied(question_id) {
1322            self.actions_applied.push(question_id.to_owned());
1323        }
1324    }
1325
1326    /// Has triage question `question_id`'s answer already been applied?
1327    pub fn triage_applied(&self, question_id: &str) -> bool {
1328        self.triage_applied.iter().any(|id| id == question_id)
1329    }
1330
1331    /// Record that a run has started for this task.
1332    /// Move an already linked run to the end so it remains the current attempt,
1333    /// with one history entry per run and separate pass records for each resume.
1334    ///
1335    /// Clears [`Task::interrupt`]: a mark to run ahead of whatever else is
1336    /// in flight is fulfilled the moment this task actually gets its turn,
1337    /// dispatched same as any other. Without this, a task whose run fails
1338    /// and requeues - still `runnable`, still carrying the mark from its
1339    /// first attempt - would keep re-triggering `crate::daemon`'s interrupt
1340    /// scheduler and re-parking whatever it interrupted on every later
1341    /// boundary, for as long as its attempts hold out, instead of the
1342    /// one-shot "let this go next" the mark is meant to be.
1343    pub fn start(&mut self, run: String) {
1344        self.stamp_schema();
1345        self.status = TaskStatus::Running;
1346        self.attempts += 1;
1347        self.runs.retain(|id| id != &run);
1348        if let Some(pin) = &self.resume_override
1349            && pin.pinned_run.as_ref() == Some(&run)
1350            && !pin.question_id.is_empty()
1351        {
1352            self.dispatched_resumes
1353                .insert(pin.question_id.clone(), run.clone());
1354        }
1355        self.runs.push(run);
1356        self.last_error = None;
1357        self.park_reason = None;
1358        self.fresh_start = false;
1359        self.interrupt = false;
1360        // The answer has been honoured: the task got its turn.
1361        self.resume_override = None;
1362    }
1363
1364    /// Attribute a failed reservation once without spending an execution attempt.
1365    pub fn record_startup_failure(&mut self, failure: crate::run::StartupFailure) {
1366        if !self.startup_failures.iter().any(|f| f.run == failure.run) {
1367            self.startup_failures.push(failure);
1368        }
1369    }
1370
1371    /// Note that `run` serves this task without otherwise changing its life:
1372    /// no status, attempt or interrupt change, unlike [`Task::start`]. For a
1373    /// run somebody else started on the task's behalf (`magi run --task`);
1374    /// idempotent. Returns whether anything was added.
1375    pub fn link_run(&mut self, run: &str) -> bool {
1376        if self.runs.iter().any(|r| r == run) {
1377            return false;
1378        }
1379        self.runs.push(run.to_owned());
1380        true
1381    }
1382
1383    /// Record a successful run.
1384    ///
1385    /// Both `magi task done` and `POST /api/queue/{id}/done` can close a held
1386    /// *or blocked* task directly, with no release in between, so this clears
1387    /// `hold_reason` and `blocked_by`/`block_reason` the same way
1388    /// [`Task::release`] does. Otherwise a task held for "waiting on 3ed9", or
1389    /// blocked on a dependency that never actually finished, and then closed
1390    /// as done without ever being released would still read as waiting on
1391    /// something in `magi task show` and on its card, after it no longer is.
1392    pub fn succeed(&mut self) {
1393        self.stamp_schema();
1394        self.status = TaskStatus::Done;
1395        self.resume_override = None;
1396        self.last_error = None;
1397        self.park_reason = None;
1398        self.hold_reason = None;
1399        self.hold_source = None;
1400        self.diagnostic = None;
1401        self.blocked_by.clear();
1402        self.block_reason = None;
1403        self.blocked_from = None;
1404    }
1405
1406    /// Finish the task because the run's whole change turned out to be on the
1407    /// base already ([`crate::run::RunStatus::AlreadyInBase`]): `Done`, with
1408    /// `note` kept in [`Task::last_error`] so `magi task show` says why, and
1409    /// the attempt refunded. Nothing went wrong and nothing was spent
1410    /// misbehaving, so this is neither [`Task::fail`] nor
1411    /// [`Task::handed_off`]; and unlike [`Task::succeed`] it does not pretend
1412    /// the run landed anything.
1413    pub fn already_landed(&mut self, note: impl Into<String>) {
1414        self.succeed();
1415        self.attempts = self.attempts.saturating_sub(1);
1416        self.last_error = Some(note.into());
1417    }
1418
1419    /// Earlier attempts at this task that a later one has since made moot —
1420    /// empty unless the task is [`TaskStatus::Done`] *and* `last_run_succeeded`
1421    /// says `runs.last()` is actually why.
1422    ///
1423    /// `runs` is oldest first, and [`Task::start`] is the only thing that
1424    /// pushes to it, always right before the attempt it names either succeeds
1425    /// or fails; `succeed` itself never touches `runs`. So whenever `status`
1426    /// is `Done` *because* the loop itself saw that last attempt land
1427    /// (`Merged`/`Ready`), everything before it in the same list is a retry
1428    /// this task no longer needs. But `succeed` is also reachable directly —
1429    /// `magi task done`, the web UI's equivalent, and the conductor's
1430    /// `Recovery::Done` all call it on a task in *any* status, including one
1431    /// whose last recorded attempt never landed at all (closed by hand after
1432    /// a merge magi's own loop never saw). `runs.last()` alone cannot tell
1433    /// those two cases apart — that requires the caller to have actually
1434    /// looked at that run's own `status`, which this module has no way to
1435    /// do — so `last_run_succeeded` is the caller's answer to exactly that
1436    /// question, not something this function can derive from `Task` alone.
1437    ///
1438    /// Deliberately narrower than [`Queue::superseded`]'s "every earlier
1439    /// attempt has a later one" walk, which fires the moment a retry starts
1440    /// even though the retry itself might still fail: that reading is right
1441    /// for the web UI's "a newer attempt exists, go look at that one
1442    /// instead" note, but wrong for deciding a run no longer needs a human's
1443    /// attention, which is only true once the task's story has actually
1444    /// ended well. Two Blocked runs sitting side by side while a third
1445    /// attempt is still in flight must not be touched by this — see
1446    /// `daemon::supersede_prior_runs`, the caller that turns this list into
1447    /// rewritten `run.json` files.
1448    pub fn superseded_attempts(&self, last_run_succeeded: bool) -> &[String] {
1449        if self.status != TaskStatus::Done || !last_run_succeeded || self.execution_runs().len() < 2
1450        {
1451            return &[];
1452        }
1453        &self.execution_runs()[..self.execution_runs().len() - 1]
1454    }
1455
1456    /// The attempt right after the last occurrence of `run`, if there is one.
1457    /// Resuming records the same run again; it cannot supersede itself.
1458    ///
1459    /// The one place "a later attempt replaced this run" is decided:
1460    /// [`Queue::superseded`] and [`Queue::superseded_by`] (the web UI's
1461    /// note) read it, and so does [`Task::earlier_attempts`], so what is shown
1462    /// and what `crate::handover` acts on cannot disagree.
1463    pub fn successor_of(&self, run: &str) -> Option<&String> {
1464        let runs = self.execution_runs();
1465        let pos = runs.iter().rposition(|r| r == run)?;
1466        runs.get(pos + 1)
1467    }
1468
1469    /// Every run in this assignment, i.e. every run that an
1470    /// attempt being minted *right now* supersedes.
1471    ///
1472    /// The new run is not in [`Task::runs`] yet when it decides what to take
1473    /// over (`Task::start` pushes it afterwards), so "has a later attempt" is
1474    /// true of everything listed here by the time the new run exists.
1475    pub fn earlier_attempts(&self) -> &[String] {
1476        self.execution_runs()
1477    }
1478
1479    /// Stamp [`Task::held_at`] on the way into [`TaskStatus::Held`]; a task
1480    /// that is already held keeps the time its hold began.
1481    /// A transition this build makes (start, hold, block, done) makes the task
1482    /// eligible for a chat notice even when it was filed under an older
1483    /// schema; only records no build has touched since stay silent
1484    /// ([`Task::chat_notice_due`]).
1485    fn stamp_schema(&mut self) {
1486        self.schema = self.schema.max(SCHEMA);
1487    }
1488
1489    fn note_held(&mut self) {
1490        self.stamp_schema();
1491        let continuing = self.status == TaskStatus::Held
1492            || (self.status == TaskStatus::Blocked
1493                && (self.blocked_from == Some(TaskStatus::Held)
1494                    || (self.blocked_from.is_none()
1495                        && (self.hold_reason.is_some() || self.hold_source.is_some()))));
1496        if !continuing || self.held_at.is_none() {
1497            self.held_at = Some(Timestamp::now());
1498        }
1499    }
1500
1501    /// Record a failed attempt. Out of attempts means held for a human, rather
1502    /// than retried until the money runs out.
1503    ///
1504    /// Clears [`Task::diagnostic`] unconditionally: it belongs to whatever run
1505    /// produced it, and a caller that has one for *this* attempt sets it
1506    /// itself right after calling this, once it knows the task actually ended
1507    /// up [`TaskStatus::Held`] - see `daemon::diagnostic`. Without the clear, a
1508    /// task released after a diagnosed hold and then failed again for an
1509    /// unrelated, undiagnosed reason (a config error, say) would go on
1510    /// showing the previous run's diagnostic as if it explained the new one.
1511    ///
1512    /// Also records `why` into [`Task::hold_reason`] when this ends up
1513    /// [`TaskStatus::Held`], so the notification and `magi task show` say the
1514    /// same thing as [`Task::last_error`] instead of leaving the hold's own
1515    /// reason blank.
1516    pub fn fail(&mut self, why: impl Into<String>, max_attempts: usize) {
1517        let why = why.into();
1518        if self.status == TaskStatus::Running {
1519            let run = self.runs.last().cloned();
1520            self.notice_cause("run-failed", run.as_deref(), Some(self.attempts));
1521        }
1522        self.diagnostic = None;
1523        self.park_reason = None;
1524        self.status = if self.attempts >= self.effective_attempt_limit(max_attempts) {
1525            self.note_held();
1526            self.hold_source = Some(HoldSource::Machine);
1527            self.hold_reason = Some(why.clone());
1528            TaskStatus::Held
1529        } else {
1530            TaskStatus::Failed
1531        };
1532        self.last_error = Some(why);
1533    }
1534
1535    /// Record an attempt that failed for a reason the task is not responsible
1536    /// for - the agent CLIs ran out of quota and the judging panel collapsed.
1537    ///
1538    /// This refunds the attempt on purpose. A quota window closing at 4am must
1539    /// not spend the backlog's retry budget: the operator would come back to a
1540    /// queue of held tasks that were never actually judged, and would have to
1541    /// release every one by hand to find out which had a real problem. The task
1542    /// goes back to `Failed`, which the loop retries, so a reset quota picks the
1543    /// work up where it stopped.
1544    pub fn stall(&mut self, why: impl Into<String>) {
1545        self.last_error = Some(why.into());
1546        self.diagnostic = None;
1547        self.attempts = self.attempts.saturating_sub(1);
1548        self.status = TaskStatus::Failed;
1549    }
1550
1551    /// Record a run that parked at a node boundary. Nothing failed: the attempt
1552    /// is refunded, [`Task::last_error`] is left as it was, the run history and
1553    /// `fresh_start` are kept so the next loop resumes the same run, and the
1554    /// reason goes to [`Task::park_reason`]. Runnable like a requeued task and
1555    /// never counted against `max_attempts`.
1556    pub fn park(&mut self, why: impl Into<String>) {
1557        self.diagnostic = None;
1558        self.attempts = self.attempts.saturating_sub(1);
1559        self.status = TaskStatus::Parked;
1560        self.park_reason = Some(why.into());
1561        // The variant and field are schema 11; stamp it so an older build
1562        // refuses the record instead of half-reading it.
1563        self.schema = self.schema.max(SCHEMA);
1564    }
1565
1566    /// Record a settled pass whose start time is unknown (see [`Self::record_pass_at`]).
1567    pub fn record_pass(
1568        &mut self,
1569        run: &str,
1570        pass_index: usize,
1571        attempts_before: usize,
1572        parked: Option<crate::run::ParkCause>,
1573    ) {
1574        self.record_pass_at(run, pass_index, None, attempts_before, parked);
1575    }
1576
1577    /// Record a settled pass. `attempts_before` is the count just before the
1578    /// settle, so a refund is read off what actually changed, not inferred.
1579    pub fn record_pass_at(
1580        &mut self,
1581        run: &str,
1582        pass_index: usize,
1583        started_at: Option<Timestamp>,
1584        attempts_before: usize,
1585        parked: Option<crate::run::ParkCause>,
1586    ) {
1587        if self
1588            .passes
1589            .iter()
1590            .any(|p| p.run == run && p.pass_index == pass_index)
1591        {
1592            return;
1593        }
1594        let cost = if self.attempts < attempts_before {
1595            PassCost::Refunded
1596        } else {
1597            PassCost::Spent
1598        };
1599        self.passes.push(TaskPass {
1600            run: run.to_owned(),
1601            pass_index,
1602            started_at: self.dispatched_at.or(started_at),
1603            cost,
1604            attempts_after: self.attempts,
1605            settled_at: Timestamp::now(),
1606            parked,
1607        });
1608        self.schema = self.schema.max(SCHEMA);
1609    }
1610
1611    /// Only the latest pass of the current, resumable upgrade-parked run
1612    /// retains its place. Explicit fresh starts and other park causes do not.
1613    pub(crate) fn upgrade_resume_key(&self) -> Option<(Timestamp, &str)> {
1614        if self.status != TaskStatus::Parked || self.fresh_start {
1615            return None;
1616        }
1617        let pass = self.passes.last()?;
1618        if self.execution_runs().last() != Some(&pass.run)
1619            || !matches!(pass.parked, Some(crate::run::ParkCause::Upgrade { .. }))
1620        {
1621            return None;
1622        }
1623        // Before schema 19 the dispatch start was not copied to the task.
1624        // Settlement time is only an approximation for those old records.
1625        Some((pass.started_at.unwrap_or(pass.settled_at), &self.id))
1626    }
1627
1628    /// Whether this held task may only be released by an operator.
1629    ///
1630    /// Old files did not record a source. Preserve every such hold rather
1631    /// than guessing that it was automatic and risking duplicate work. New
1632    /// automatic holds record [`HoldSource::Machine`] and remain recoverable.
1633    pub fn operator_held(&self) -> bool {
1634        self.status == TaskStatus::Held && !matches!(self.hold_source, Some(HoldSource::Machine))
1635    }
1636
1637    /// Take this task out of the loop's reach by an operator action.
1638    ///
1639    /// Clears `blocked_by`/`block_reason` unconditionally, the same as
1640    /// [`Task::release`] and for the same reason its own comment already
1641    /// gives: a human choosing to hold a *blocked* task overrides its wait
1642    /// outright, the same as it overrides an ordinary hold. Without this, a
1643    /// task held straight out of [`TaskStatus::Blocked`] - the web UI's "Hold"
1644    /// button is reachable on a blocked task, same as "Mark done" - kept
1645    /// reading as still waiting on a dependency it no longer had any claim on.
1646    pub fn hold_manual(&mut self, reason: Option<String>) {
1647        // A later explicit hold supersedes outstanding triage answers.
1648        self.operator_decided_at = Some(Timestamp::now());
1649        self.hold_unrequested_retry(reason);
1650    }
1651
1652    /// Keep a hand-started run from retrying automatically, without recording
1653    /// an operator decision that could invalidate its outstanding questions.
1654    pub(crate) fn hold_unrequested_retry(&mut self, reason: Option<String>) {
1655        self.park_reason = None;
1656        self.note_held();
1657        self.status = TaskStatus::Held;
1658        if reason.is_some() {
1659            self.hold_reason = reason;
1660        }
1661        self.hold_source = Some(HoldSource::Manual);
1662        self.blocked_by.clear();
1663        self.block_reason = None;
1664        self.blocked_from = None;
1665    }
1666
1667    /// Take this task out of the loop's reach during automatic recovery.
1668    ///
1669    /// Clears `blocked_by`/`block_reason` for the same reason
1670    /// [`Task::hold_manual`] does.
1671    pub fn hold_machine(&mut self, reason: Option<String>) {
1672        self.park_reason = None;
1673        self.note_held();
1674        self.status = TaskStatus::Held;
1675        if reason.is_some() {
1676            self.hold_reason = reason;
1677        }
1678        self.hold_source = Some(HoldSource::Machine);
1679        self.blocked_by.clear();
1680        self.block_reason = None;
1681        self.blocked_from = None;
1682    }
1683
1684    /// Block this task on other task ids and/or open question ids, chosen by
1685    /// `crate::conduct`. Pure: the caller still owns writing it back with
1686    /// [`Queue::put`].
1687    ///
1688    /// Records [`Task::blocked_from`] the first time this moves the task into
1689    /// [`TaskStatus::Blocked`], and leaves it alone on a later call that adds
1690    /// or replaces `blocked_by` while the task is already `Blocked` - a
1691    /// second question about an already-blocked task must not overwrite the
1692    /// status it should eventually return to with `Blocked` itself.
1693    pub fn block(&mut self, blocked_by: Vec<String>, reason: Option<String>) {
1694        self.stamp_schema();
1695        let before: std::collections::BTreeSet<_> = self.blocked_by.iter().collect();
1696        let after: std::collections::BTreeSet<_> = blocked_by.iter().collect();
1697        if self.status != TaskStatus::Blocked || before != after {
1698            self.blocked_at = Some(Timestamp::now());
1699        }
1700        if self.status != TaskStatus::Blocked {
1701            self.blocked_from = Some(self.status);
1702        }
1703        self.status = TaskStatus::Blocked;
1704        self.blocked_by = blocked_by;
1705        self.block_reason = reason;
1706    }
1707
1708    /// Remove one resolved dependency (a task id that became [`TaskStatus::Done`],
1709    /// or a question id that became [`crate::ask::QuestionStatus::Answered`]).
1710    /// Once nothing is left in [`Task::blocked_by`], the task returns to
1711    /// whatever [`Task::blocked_from`] recorded - deciding *why* a task was
1712    /// blocked was `crate::conduct`'s job, but noticing a dependency resolved
1713    /// needs no model at all, and restoring the status it interrupted needs
1714    /// nothing more than what `block` already wrote down.
1715    ///
1716    /// A task blocked while `Running` restores to [`TaskStatus::Queued`]
1717    /// instead: whatever process was running it is gone by the time this
1718    /// runs, so there is nothing left to resume. A task with no recorded
1719    /// `blocked_from` - a pre-schema-4 record, or one blocked before this
1720    /// field existed - falls back to [`TaskStatus::Held`] when it still
1721    /// carries hold evidence ([`Task::hold_reason`] or [`Task::hold_source`],
1722    /// neither ever cleared by `block`), and to `Queued` otherwise: the same
1723    /// choice `block` itself would have recorded, reconstructed from what
1724    /// survived.
1725    ///
1726    /// A no-op, on purpose, for a task that is not [`TaskStatus::Blocked`]:
1727    /// `crate::daemon`'s deterministic resolver runs over every task on every
1728    /// poll, and a task that moved on for some other reason must not be
1729    /// dragged back by a stale id it still happens to carry.
1730    pub fn unblock(&mut self, resolved_id: &str) {
1731        if self.status != TaskStatus::Blocked {
1732            return;
1733        }
1734        self.blocked_by.retain(|id| id != resolved_id);
1735        self.restore_if_unblocked();
1736    }
1737
1738    /// A dependency this task waited on was deleted on purpose
1739    /// ([`Queue::remove`]): drop just that id from [`Task::blocked_by`] and,
1740    /// once nothing is left, return to the status the block interrupted, the
1741    /// same way [`Task::unblock`] does. Returns whether anything changed.
1742    ///
1743    /// Never a hold: the operator chose the deletion, so the dependent is not
1744    /// in trouble. Touches nothing but a `Blocked` task that actually names
1745    /// `deleted_id`, so a `Held` task (or a manual hold) is left exactly as it
1746    /// was. A dependency that vanished *without* going through a deletion is
1747    /// not this method's case - that stays a machine hold.
1748    pub fn dependency_deleted(&mut self, deleted_id: &str) -> bool {
1749        if self.status != TaskStatus::Blocked || !self.blocked_by.iter().any(|b| b == deleted_id) {
1750            return false;
1751        }
1752        self.blocked_by.retain(|id| id != deleted_id);
1753        self.restore_if_unblocked();
1754        true
1755    }
1756
1757    /// The shared tail of [`Task::unblock`] and [`Task::dependency_deleted`]:
1758    /// with nothing left in `blocked_by`, restore the interrupted status and
1759    /// clear the now-stale block bookkeeping.
1760    fn restore_if_unblocked(&mut self) {
1761        if self.blocked_by.is_empty() {
1762            self.status = match self.blocked_from {
1763                Some(TaskStatus::Running) => TaskStatus::Queued,
1764                Some(other) => other,
1765                None if self.hold_reason.is_some() || self.hold_source.is_some() => {
1766                    TaskStatus::Held
1767                }
1768                None => TaskStatus::Queued,
1769            };
1770            self.block_reason = None;
1771            self.blocked_from = None;
1772        }
1773    }
1774
1775    /// Record that a question `crate::conduct` asked about this task has been
1776    /// answered, so the answer's content — not just the fact that the
1777    /// question is gone — reaches the next conductor prompt and the next
1778    /// run's instruction. See [`Task::answers`].
1779    pub fn record_answer(&mut self, question: String, answer: String) {
1780        self.answers.push(AnsweredQuestion { question, answer });
1781    }
1782
1783    /// Requeue this task to reopen its last run as a review-only pass against
1784    /// `branch` (`crate::graph::Runner::review`) rather than competing from
1785    /// scratch. See [`Task::review_branch`].
1786    pub fn request_review(&mut self, branch: String) {
1787        self.release();
1788        self.review_branch = Some(branch);
1789        self.review_instruction = Some(self.instruction.clone());
1790    }
1791
1792    /// Requeue after a conductor chose a new competition. Unlike an ordinary
1793    /// operator release, this deliberately does not resume the old run.
1794    pub fn requeue(&mut self) {
1795        self.release();
1796        // A fresh competition is the opposite of a review of the old branch.
1797        self.review_branch = None;
1798        self.review_instruction = None;
1799        self.fresh_start = true;
1800    }
1801
1802    /// Hold this task because a takeover of `branch` was refused, keeping
1803    /// [`Task::review_branch`] so that once the operator has cleaned up and
1804    /// released it, the retry is a review of the same branch rather than a
1805    /// resume or a fresh competition. Spends no attempt.
1806    ///
1807    /// This is the only way a machine hold keeps a `review_branch`: the
1808    /// daemon takes it at the start of every attempt, so [`Task::release`]
1809    /// relies on that to tell this hold from every other.
1810    pub fn hold_for_handover(&mut self, branch: Option<String>, reason: String) {
1811        if branch.is_some() {
1812            self.review_branch = branch;
1813            self.review_instruction = Some(self.instruction.clone());
1814        }
1815        self.hold_machine(Some(reason));
1816    }
1817
1818    /// Change the urgent lane setting without releasing a held task.
1819    pub fn set_urgent(&mut self, urgent: bool) -> Result<()> {
1820        if !matches!(self.status, TaskStatus::Queued | TaskStatus::Held) {
1821            bail!(
1822                "task {} is {}; urgent can only change while queued or held; \
1823                 wait for the active attempt to finish and requeue or hold the task first",
1824                self.short(),
1825                self.status.as_str()
1826            );
1827        }
1828        self.urgent = urgent;
1829        Ok(())
1830    }
1831
1832    /// Change how urgently this task should run next.
1833    ///
1834    /// Refused once the task is `running`: priority only feeds the sort
1835    /// [`Queue::next_runnable`] does over tasks waiting to be claimed, and a
1836    /// running task has already left that pool. Accepting the write anyway
1837    /// would look like it worked while changing nothing until - and unless -
1838    /// this attempt fails and the task becomes runnable again, which is a
1839    /// surprise the phone should not hand back as a success.
1840    pub fn set_priority(&mut self, priority: i32) -> Result<()> {
1841        if self.status == TaskStatus::Running {
1842            bail!(
1843                "task {} is running; its priority cannot be changed until \
1844                 this attempt finishes",
1845                self.short()
1846            );
1847        }
1848        self.priority = priority;
1849        Ok(())
1850    }
1851
1852    /// Mark (or unmark) this task to interrupt whatever `magi serve` already
1853    /// has in flight, once `[daemon] pause_for_interrupts` is on. See
1854    /// [`Task::interrupt`].
1855    ///
1856    /// Setting it is restricted to a task the loop could pick up on its own
1857    /// right now - [`TaskStatus::runnable`] - for the same reason as
1858    /// [`Task::set_priority`]: a task already `running` has been claimed, and
1859    /// a task that is `done`, `held`, or `blocked` is not going to compete
1860    /// for the daemon's attention regardless of this flag. Unlike priority,
1861    /// this is never silently inert while `running` - it is refused outright,
1862    /// because the entire feature this flag drives (`crate::daemon`'s
1863    /// interrupt scheduler) is scoped to tasks still waiting to be claimed.
1864    /// Clearing it back to `false` carries no such risk and is always
1865    /// allowed, including on a task that moved on since it was set.
1866    pub fn set_interrupt(&mut self, interrupt: bool) -> Result<()> {
1867        if interrupt && !self.status.runnable() {
1868            bail!(
1869                "task {} is {}; only a queued or failed task can be marked \
1870                 to interrupt",
1871                self.short(),
1872                self.status.as_str()
1873            );
1874        }
1875        self.interrupt = interrupt;
1876        Ok(())
1877    }
1878
1879    /// Resolve the task override against the running daemon's limit.
1880    pub fn effective_attempt_limit(&self, daemon_limit: usize) -> usize {
1881        self.attempt_limit.map_or(daemon_limit, NonZeroUsize::get)
1882    }
1883
1884    /// Change the budget without resetting attempts or releasing a hold.
1885    /// Callers must hold the queue claim and reload the task before calling.
1886    pub fn change_attempt_limit(&mut self, limit: Option<NonZeroUsize>) -> Result<()> {
1887        if !matches!(self.status, TaskStatus::Queued | TaskStatus::Held) {
1888            bail!("only queued or held tasks can change the attempt limit");
1889        }
1890        self.stamp_schema();
1891        self.attempt_limit = limit;
1892        Ok(())
1893    }
1894
1895    /// Explicit implementer choice, with Solo taking precedence for old records.
1896    pub fn implementers(&self) -> Option<usize> {
1897        if self.solo {
1898            Some(1)
1899        } else {
1900            self.overrides.as_ref().and_then(|o| o.candidates)
1901        }
1902    }
1903
1904    /// Validate against this task's configuration and change only its seat count.
1905    /// Callers must hold the queue claim and reload the task before calling.
1906    pub fn change_implementers(&mut self, count: u8) -> Result<()> {
1907        self.check_implementers_editable()?;
1908        let explicit = self.overrides.as_ref().and_then(|o| o.config.as_deref());
1909        let (mut config, _) = crate::config::Config::discover(&self.repo, explicit)?;
1910        if let Some(o) = &self.overrides {
1911            o.apply(&mut config);
1912        }
1913        self.set_implementers(count, &config)
1914    }
1915
1916    fn check_implementers_editable(&self) -> Result<()> {
1917        if !matches!(self.status, TaskStatus::Queued | TaskStatus::Held) {
1918            bail!(
1919                "task {} is {}; only queued or held tasks can change implementers",
1920                self.short(),
1921                self.status.as_str()
1922            );
1923        }
1924        Ok(())
1925    }
1926
1927    /// Normalize Solo and candidate overrides without altering task history.
1928    pub fn set_implementers(&mut self, count: u8, config: &crate::config::Config) -> Result<()> {
1929        self.check_implementers_editable()?;
1930        crate::talk::check_implementers(count, config).map_err(anyhow::Error::msg)?;
1931        self.stamp_schema();
1932        self.solo = count == 1;
1933        let mut overrides = self.overrides.clone().unwrap_or_else(|| RunOverrides {
1934            inherit_daemon_options: true,
1935            ..Default::default()
1936        });
1937        overrides.candidates = (count > 1).then_some(usize::from(count));
1938        let mut settings = overrides.clone();
1939        settings.inherit_daemon_options = false;
1940        // Some(empty) is a direct-run setting too: retain its isolation on Solo.
1941        self.overrides = if overrides.inherit_daemon_options && settings == RunOverrides::default()
1942        {
1943            None
1944        } else {
1945            Some(overrides)
1946        };
1947        Ok(())
1948    }
1949
1950    /// Replace this task's title and instruction wholesale.
1951    ///
1952    /// Restricted to `queued` and `held`. A `running` task's instruction has
1953    /// already been handed to the graph, so a run in flight and the file on
1954    /// disk must not be allowed to disagree about what was asked; a `done` or
1955    /// `failed` task is a record of what actually happened and editing it
1956    /// after the fact would falsify that record. `id`, `created_at`,
1957    /// `source`, and `runs` are left untouched on purpose - an edit stands in
1958    /// for "delete and refile", and keeping the id, the timestamp, the
1959    /// attribution, and the run history is the entire reason it exists
1960    /// instead.
1961    pub fn edit(&mut self, title: String, instruction: String) -> Result<()> {
1962        if !matches!(self.status, TaskStatus::Queued | TaskStatus::Held) {
1963            bail!(
1964                "task {} is {}; only a queued or held task's instruction can \
1965                 be edited",
1966                self.short(),
1967                self.status.as_str()
1968            );
1969        }
1970        // Older retained reviews have no criteria snapshot yet. Capture the
1971        // old instruction before this supported edit can change the target.
1972        if self.review_branch.is_some() && self.review_instruction.is_none() {
1973            self.review_instruction = Some(self.instruction.clone());
1974        }
1975        if self.instruction != instruction {
1976            // A run selected for earlier criteria is no longer authorized by
1977            // this revised instruction. Title-only edits preserve the pin.
1978            self.resume_override = None;
1979        }
1980        self.title = title;
1981        self.instruction = instruction;
1982        Ok(())
1983    }
1984
1985    /// Record a run that produced a pull request without merging it.
1986    ///
1987    /// The task is held rather than retried, and it costs no further attempt
1988    /// either way. The work the task asked for exists: it is sitting on a
1989    /// branch, in a pull request, waiting for CI or for a person. Retrying
1990    /// would spend the whole competition budget a second time and then race a
1991    /// second branch against the pull request the first one opened - which is
1992    /// exactly what happened to run 01c2, whose finished and green pull request
1993    /// was re-competed from scratch four seconds after it opened.
1994    ///
1995    /// A pull request nobody merged is a request for a person, not a failure.
1996    ///
1997    /// Records `why` into [`Task::hold_reason`] as well as
1998    /// [`Task::last_error`], so the notification centre and `magi task show`
1999    /// say why the task is held rather than "no reason recorded". This is
2000    /// also the path a verified no-op with an outstanding `magi ask` question
2001    /// settles through - see `daemon::settle` and `daemon::settle_and_diagnose`,
2002    /// which append the question id to `hold_reason` when one is still open
2003    /// for the run.
2004    pub fn handed_off(&mut self, why: impl Into<String>) {
2005        let why = why.into();
2006        self.diagnostic = None;
2007        self.note_held();
2008        self.status = TaskStatus::Held;
2009        self.hold_source = Some(HoldSource::Machine);
2010        self.hold_reason = Some(why.clone());
2011        self.last_error = Some(why);
2012    }
2013
2014    /// Release on explicit operator authority, rather than automatic recovery.
2015    pub fn release_operator(&mut self, source: &str, question_id: Option<&str>) {
2016        self.recovery_budget = None;
2017        self.recovery_generations.clear();
2018        self.recovery_admission = None;
2019        if self
2020            .resumption
2021            .as_ref()
2022            .is_some_and(|r| r.instruction != self.instruction)
2023        {
2024            // Also cover persisted revisions whose earlier approval still
2025            // carries a transient pin when this release is applied.
2026            self.resume_override = None;
2027        }
2028        let approval = Resumption {
2029            generation: self.resumption.as_ref().map_or(1, |r| r.generation + 1),
2030            source: source.to_owned(),
2031            question_id: question_id.map(str::to_owned),
2032            at: Timestamp::now(),
2033            instruction: self.instruction.clone(),
2034            answers_through: self.answers.len(),
2035            runs_through: self.runs.len(),
2036            blocking_evidence: Vec::new(),
2037            cleared_reason: self
2038                .hold_reason
2039                .clone()
2040                .or_else(|| self.block_reason.clone()),
2041        };
2042        self.release();
2043        self.operator_decided_at = Some(approval.at);
2044        if let Some(previous) = self.resumption.replace(approval) {
2045            self.resumption_history.push(previous);
2046        }
2047    }
2048
2049    /// Record a failed graph pass without allowing automatic requeues to refund it.
2050    pub(crate) fn recovery_failed(&mut self, state: &crate::run::RunState) {
2051        let (base, inputs) = self.recovery_admission.as_ref().map_or_else(
2052            || (state.base_commit.clone(), recovery_inputs(&state.sources)),
2053            |a| (a.base.clone(), a.inputs.clone()),
2054        );
2055        let progress = recovery_progress(state);
2056        let stage = if state.prep_failure.is_some() {
2057            "preparation"
2058        } else {
2059            "execution"
2060        };
2061        let matches = |b: &RecoveryBudget| {
2062            b.instruction == self.instruction
2063                && b.base == base
2064                && b.inputs == inputs
2065                && (progress.is_none() || b.progress == progress)
2066        };
2067        if !self.recovery_budget.as_ref().is_some_and(matches) {
2068            let previous = self
2069                .recovery_generations
2070                .iter()
2071                .position(matches)
2072                .map(|index| self.recovery_generations.remove(index));
2073            if let Some(old) = self.recovery_budget.take() {
2074                self.recovery_generations.push(old);
2075            }
2076            self.recovery_budget = previous;
2077        }
2078        if let Some(budget) = &mut self.recovery_budget {
2079            budget.failures = budget.failures.saturating_add(1);
2080            budget.stage = stage.to_owned();
2081        } else {
2082            self.recovery_budget = Some(RecoveryBudget {
2083                instruction: self.instruction.clone(),
2084                base,
2085                inputs,
2086                stage: stage.to_owned(),
2087                failures: 1,
2088                progress,
2089            });
2090        }
2091    }
2092
2093    pub(crate) fn recovery_exhausted(
2094        &self,
2095        base: &str,
2096        inputs: &str,
2097        limit: usize,
2098    ) -> Option<String> {
2099        let same_input = |b: &&RecoveryBudget| {
2100            b.instruction == self.instruction && b.base == base && b.inputs == inputs
2101        };
2102        let budget = self
2103            .recovery_budget
2104            .as_ref()
2105            .filter(same_input)
2106            .or_else(|| self.recovery_generations.iter().rev().find(same_input))?;
2107        (budget.instruction == self.instruction && budget.base == base && budget.inputs == inputs
2108            && budget.failures >= limit.max(1)).then(|| format!(
2109                "[recovery-budget] {} failed passes against unchanged inputs ({}). Inspect the retained recovery sources and correct the cause, change the inputs, or explicitly release the task to approve another generation. Automatic requeue does not reset this budget.",
2110                budget.failures, budget.stage))
2111    }
2112
2113    /// Put a held or finished task back in line, with its attempt count reset
2114    /// so a release is a real second chance rather than an instant re-hold.
2115    /// The run history is kept: attempts reset, evidence does not.
2116    pub fn release(&mut self) {
2117        // Freeze the unresolved cause before a recovery can mint a run without
2118        // doing work. Approval and timestamps alone are not new outcomes.
2119        self.import_chat_notice();
2120        if self.hold_notice_cause.is_none()
2121            && matches!(self.status, TaskStatus::Held | TaskStatus::Blocked)
2122        {
2123            self.hold_notice_cause = Some(self.unresolved_hold_cause());
2124        }
2125        let refused_handover = self.status == TaskStatus::Held
2126            && self.hold_source == Some(HoldSource::Machine)
2127            && self.review_branch.is_some()
2128            && self
2129                .review_instruction
2130                .as_ref()
2131                .is_none_or(|i| *i == self.instruction);
2132        self.status = TaskStatus::Queued;
2133        self.held_at = None;
2134        self.attempts = 0;
2135        self.last_error = None;
2136        self.park_reason = None;
2137        // Otherwise the next person who holds this task reads a reason that
2138        // belonged to whatever it was waiting on last time.
2139        self.hold_reason = None;
2140        self.hold_source = None;
2141        self.diagnostic = None;
2142        // A release also un-blocks: the dependency or question `blocked_by`
2143        // named may still be unresolved, but a human (or `crate::conduct`)
2144        // choosing to release the task overrides that wait outright, the same
2145        // as it overrides an ordinary hold.
2146        self.blocked_by.clear();
2147        self.block_reason = None;
2148        self.blocked_from = None;
2149        // A machine hold that still names a review branch is a refused
2150        // handover (see [`Task::hold_for_handover`]): the retry must review
2151        // that same branch. Any other release drops it.
2152        if !refused_handover {
2153            self.review_branch = None;
2154            self.review_instruction = None;
2155        }
2156        self.fresh_start = false;
2157    }
2158}
2159
2160/// Copy `src` into `dir` as `name`, or `stem-2.ext`, `stem-3.ext`, ... when
2161/// that is taken. `create_new` makes the collision check atomic and also
2162/// catches a case-insensitive filesystem. Returns the stored name and path.
2163fn copy_new(dir: &Path, src: &Path, name: &str) -> Result<(String, PathBuf)> {
2164    use std::io::ErrorKind;
2165    let (stem, ext) = match name.rfind('.') {
2166        Some(i) if i > 0 => (&name[..i], &name[i..]),
2167        _ => (name, ""),
2168    };
2169    for n in 1u32.. {
2170        let candidate = if n == 1 {
2171            name.to_owned()
2172        } else {
2173            let suffix = format!("-{n}");
2174            let room = 64usize.saturating_sub(suffix.len() + ext.len());
2175            let stem: String = stem.chars().take(room).collect();
2176            format!("{stem}{suffix}{ext}")
2177        };
2178        if !crate::ask::valid_asset_name(&candidate) {
2179            bail!("no valid attachment name is left for `{name}`");
2180        }
2181        let path = dir.join(&candidate);
2182        match std::fs::OpenOptions::new()
2183            .write(true)
2184            .create_new(true)
2185            .open(&path)
2186        {
2187            Ok(mut out) => {
2188                let copied = std::fs::File::open(src)
2189                    .and_then(|mut input| std::io::copy(&mut input, &mut out));
2190                if let Err(e) = copied {
2191                    drop(out);
2192                    let _ = std::fs::remove_file(&path);
2193                    return Err(e).with_context(|| format!("copy {}", src.display()));
2194                }
2195                return Ok((candidate, path));
2196            }
2197            Err(e) if e.kind() == ErrorKind::AlreadyExists => continue,
2198            Err(e) => return Err(e).with_context(|| format!("create {}", path.display())),
2199        }
2200    }
2201    unreachable!("the counter never runs out")
2202}
2203
2204/// Minimum age before a dead writer's lock may be recovered, and maximum wait
2205/// for a contending writer. Age alone never revokes a live writer's ownership.
2206const TASK_LOCK_STALE: std::time::Duration = std::time::Duration::from_secs(10);
2207
2208/// Guard for [`Queue::lock_task`]; removes the lock file on drop, but only
2209/// while the file still carries this guard's owner token.
2210pub(crate) struct TaskLock {
2211    path: PathBuf,
2212    token: String,
2213}
2214
2215/// A token no other holder shares: pid, then a mix of entropy and a process
2216/// counter so threads born in the same nanosecond still differ.
2217fn owner_token() -> String {
2218    static COUNTER: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(0);
2219    let n = COUNTER.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
2220    let mut r = crate::rng::SplitMix64::new(crate::rng::entropy() ^ n.rotate_left(32));
2221    format!("{}-{:016x}", std::process::id(), r.next_u64())
2222}
2223
2224/// The marker that serializes everyone removing the lock that carries `token`.
2225/// Hashed (FNV-1a) so an empty or foreign token is still a valid file name.
2226fn break_marker(path: &Path, token: &str) -> PathBuf {
2227    let mut h: u64 = 0xcbf29ce484222325;
2228    for b in token.bytes() {
2229        h ^= u64::from(b);
2230        h = h.wrapping_mul(0x100000001b3);
2231    }
2232    let mut name = path.as_os_str().to_owned();
2233    name.push(format!(".break-{h:016x}"));
2234    PathBuf::from(name)
2235}
2236
2237fn older_than_stale(path: &Path) -> bool {
2238    std::fs::metadata(path)
2239        .and_then(|m| m.modified())
2240        .ok()
2241        .and_then(|t| t.elapsed().ok())
2242        .is_some_and(|age| age > TASK_LOCK_STALE)
2243}
2244
2245fn writer_may_be_gone(token: &str) -> bool {
2246    let Some(pid) = token
2247        .split_once('-')
2248        .and_then(|(pid, _)| pid.parse::<u32>().ok())
2249    else {
2250        // Legacy/incomplete tokens have no valid writer identity. They remain
2251        // subject to the age and compare/remove checks.
2252        return true;
2253    };
2254    if pid == std::process::id() {
2255        return false;
2256    }
2257    // Unknown process-table access must not steal a long-running retirement.
2258    crate::proc::pid_status(pid) == Some(false)
2259}
2260
2261/// How many levels of "a stale marker guarding a stale marker" are recovered
2262/// before giving up. Each level needs its own crashed remover, so the cap is
2263/// never reached without several independent crashes.
2264const MAX_MARKER_DEPTH: u8 = 3;
2265
2266/// Take the break marker for `token`, or `None` if another remover holds it.
2267/// The marker carries its own owner token. One older than [`TASK_LOCK_STALE`]
2268/// was left by a remover that died; it is cleared by the same compare-and-
2269/// remove discipline as a lock, guarded by a marker of its own, so a recoverer
2270/// that judged it stale cannot delete a fresh marker that replaced it.
2271fn take_marker(
2272    path: &Path,
2273    token: &str,
2274    depth: u8,
2275    retry: crate::lock_file::Retry,
2276) -> Option<(PathBuf, String)> {
2277    use std::io::Write;
2278    let marker = break_marker(path, token);
2279    for _ in 0..2 {
2280        match retry.create(&marker) {
2281            Ok(mut f) => {
2282                let mine = owner_token();
2283                if f.write_all(mine.as_bytes()).is_err() {
2284                    drop(f);
2285                    let _ = std::fs::remove_file(&marker);
2286                    return None;
2287                }
2288                return Some((marker, mine));
2289            }
2290            Err(e) if e.kind() == std::io::ErrorKind::AlreadyExists => {
2291                let judged = std::fs::read_to_string(&marker).ok();
2292                match judged.filter(|_| older_than_stale(&marker)) {
2293                    Some(judged) if depth < MAX_MARKER_DEPTH => {
2294                        remove_lock_if(&marker, &judged, true, depth + 1, retry)?;
2295                    }
2296                    _ => return None,
2297                }
2298            }
2299            Err(_) => return None,
2300        }
2301    }
2302    None
2303}
2304
2305/// Remove the lock at `path` if it still carries `token` (and, when
2306/// `require_stale`, is still stale). Removal is serialized per token by the
2307/// break marker, so a remover that judged an old lock cannot delete the fresh
2308/// one that replaced it. `None` means the marker was busy: try again.
2309fn remove_lock_if(
2310    path: &Path,
2311    token: &str,
2312    require_stale: bool,
2313    depth: u8,
2314    retry: crate::lock_file::Retry,
2315) -> Option<bool> {
2316    let (marker, mine) = take_marker(path, token, depth, retry)?;
2317    let still = std::fs::read_to_string(path).is_ok_and(|c| c == token)
2318        && (!require_stale || older_than_stale(path) && writer_may_be_gone(token));
2319    if still {
2320        let _ = std::fs::remove_file(path);
2321    }
2322    // Release the marker only if it is still ours.
2323    if depth >= MAX_MARKER_DEPTH {
2324        if std::fs::read_to_string(&marker).is_ok_and(|c| c == mine) {
2325            let _ = std::fs::remove_file(&marker);
2326        }
2327    } else {
2328        let _ = remove_lock_if(&marker, &mine, false, depth + 1, retry);
2329    }
2330    Some(still)
2331}
2332
2333/// Break the lock judged stale while it held `judged`. Returns whether it was
2334/// removed; a lock that has since been replaced is left alone.
2335#[cfg(test)]
2336fn break_stale(path: &Path, judged: &str) -> bool {
2337    break_stale_with(path, judged, crate::lock_file::Retry::new(None))
2338}
2339
2340fn break_stale_with(path: &Path, judged: &str, retry: crate::lock_file::Retry) -> bool {
2341    remove_lock_if(path, judged, true, 0, retry).unwrap_or(false)
2342}
2343
2344impl Drop for TaskLock {
2345    fn drop(&mut self) {
2346        let deadline = std::time::Instant::now() + std::time::Duration::from_secs(2);
2347        let retry = crate::lock_file::Retry::new(Some(deadline));
2348        loop {
2349            match remove_lock_if(&self.path, &self.token, false, 0, retry) {
2350                Some(_) => return,
2351                None if std::time::Instant::now() > deadline => return,
2352                None => std::thread::sleep(std::time::Duration::from_millis(5)),
2353            }
2354        }
2355    }
2356}
2357
2358/// A queue on disk.
2359#[derive(Debug, Clone)]
2360pub struct Queue {
2361    root: PathBuf,
2362    ids: IdSource,
2363}
2364
2365fn validate_attachments(sources: &[PathBuf]) -> Result<Vec<(&PathBuf, &str)>> {
2366    let mut wanted = Vec::new();
2367    for src in sources {
2368        let name = src
2369            .file_name()
2370            .and_then(|n| n.to_str())
2371            .with_context(|| format!("`{}` has no usable file name", src.display()))?;
2372        if !crate::ask::valid_asset_name(name) {
2373            bail!(
2374                "attachment name `{name}` must match ^[A-Za-z0-9][A-Za-z0-9._-]{{0,63}}$ \
2375                 with no `..`; rename the file and try again"
2376            );
2377        }
2378        if !src.is_file() {
2379            bail!("attachment `{}` is not a file", src.display());
2380        }
2381        wanted.push((src, name));
2382    }
2383    Ok(wanted)
2384}
2385
2386impl Queue {
2387    /// The operator's queue, `<home>/queue`.
2388    pub fn open() -> Self {
2389        Self::at(crate::run::home().join("queue"))
2390    }
2391
2392    /// A queue at an explicit root. Tests use this; so could an operator who
2393    /// wants a queue per project.
2394    pub fn at(root: PathBuf) -> Self {
2395        Self {
2396            root,
2397            ids: IdSource::new(new_id),
2398        }
2399    }
2400
2401    /// Replace the source of candidate ids for new tasks. For tests that need
2402    /// a deterministic collision.
2403    #[doc(hidden)]
2404    pub fn with_id_source(mut self, f: impl Fn() -> String + Send + Sync + 'static) -> Self {
2405        self.ids = IdSource::custom(f);
2406        self
2407    }
2408
2409    /// File a new task: reserve its id atomically and write it without ever
2410    /// reading, merging into or replacing an existing record.
2411    ///
2412    /// The candidate is `task.id`. Under that id's write lock, a record that
2413    /// already exists makes the candidate taken and another id is minted; a
2414    /// failure to find out is an error, never "free". `hook` runs under the
2415    /// lock once the id looks free and may veto it with `Ok(false)` (an
2416    /// orphaned claim or attachment directory also marks an id as used). The
2417    /// first `Err` ends the attempt. `undo` runs if the record then fails to
2418    /// write. `task.id` is the reserved id on success.
2419    fn file_with(
2420        &self,
2421        task: &mut Task,
2422        hook: impl FnMut(&mut Task) -> Result<bool>,
2423        undo: impl FnMut(&mut Task),
2424    ) -> Result<()> {
2425        self.reserve_id(task, hook, undo, true)
2426    }
2427
2428    /// The reservation loop behind [`Queue::file_with`]. With `store` false
2429    /// the id is only reserved through whatever `hook` leaves on disk (an
2430    /// attachment directory) and no record is written; the task stays unfiled.
2431    ///
2432    /// An injected id source supplies the first candidate too, unless the
2433    /// task already holds an id through an earlier reservation (attachments);
2434    /// production keeps the id [`Task::new`] minted.
2435    fn reserve_id(
2436        &self,
2437        task: &mut Task,
2438        mut hook: impl FnMut(&mut Task) -> Result<bool>,
2439        mut undo: impl FnMut(&mut Task),
2440        store: bool,
2441    ) -> Result<()> {
2442        let redraw_first = self.ids.is_custom() && task.attachments.is_empty();
2443        let initial = task.id.clone();
2444        self.ids
2445            .reserve((!redraw_first).then_some(initial.as_str()), "task", |id| {
2446                task.id = id.to_owned();
2447                let _lock = self.lock_task(&task.id)?;
2448                if path_exists(&self.path_of(&task.id))? || !hook(task)? {
2449                    return Ok(false);
2450                }
2451                if store {
2452                    if let Err(e) = self.write_record(task) {
2453                        undo(task);
2454                        return Err(e);
2455                    }
2456                    task.unfiled = false;
2457                }
2458                Ok(true)
2459            })?;
2460        Ok(())
2461    }
2462
2463    /// Is `id` used by anything but a stored record: a claim file, or an
2464    /// attachment directory (`check_attachments`) left by an earlier
2465    /// reservation or an interrupted filing? Only a definite "not found" is
2466    /// free; any other answer is an error, never "free".
2467    fn id_in_use(&self, id: &str, check_attachments: bool) -> Result<bool> {
2468        if path_exists(&self.lock_path(id))? {
2469            return Ok(true);
2470        }
2471        Ok(check_attachments && path_exists(&self.attachments_dir(id))?)
2472    }
2473
2474    /// The `hook` of a plain [`Queue::put`] of a new task. Attachments
2475    /// already copied by [`Queue::attach`] sit in this id's own directory,
2476    /// which is then not a sign of someone else's use.
2477    fn plain_filing_hook(&self, task: &Task) -> Result<bool> {
2478        Ok(!self.id_in_use(&task.id, task.attachments.is_empty())?)
2479    }
2480
2481    /// File a new task and take its claim in one step, on the id that ends up
2482    /// reserved. An id whose claim file already exists is taken.
2483    pub fn file_claimed(&self, task: &mut Task) -> Result<Claim> {
2484        let mut claim = None;
2485        self.file_with(
2486            task,
2487            |t| {
2488                if self.id_in_use(&t.id, true)? {
2489                    return Ok(false);
2490                }
2491                claim = Some(self.claim(&t.id)?);
2492                Ok(true)
2493            },
2494            |_| {},
2495        )?;
2496        claim.context("claim missing after filing")
2497    }
2498
2499    /// Directory holding the task files.
2500    pub fn root(&self) -> &Path {
2501        &self.root
2502    }
2503
2504    /// Path for one task id.
2505    pub fn path_of(&self, id: &str) -> PathBuf {
2506        self.root.join(format!("{id}.json"))
2507    }
2508
2509    /// Directory holding a task's attachments. A sibling of the task file,
2510    /// not a `*.json`, so [`Queue::list`] and [`Queue::revision`] never see it.
2511    pub fn attachments_dir(&self, id: &str) -> PathBuf {
2512        self.root.join(format!("{id}.attachments"))
2513    }
2514
2515    /// Copy each of `sources` into `task`'s attachment directory and record
2516    /// the stored names on `task` (persist with [`Queue::put`]). Returns the
2517    /// names, in order.
2518    ///
2519    /// Every source is checked (a readable file, a name passing
2520    /// [`crate::ask::valid_asset_name`]) before anything is copied, and a
2521    /// copy that fails part-way removes only what this call created. A name
2522    /// already taken is never overwritten: it becomes `stem-2.ext`,
2523    /// `stem-3.ext`, ... A name that does not validate is refused rather than
2524    /// sanitised - the operator renames the file.
2525    pub fn attach(&self, task: &mut Task, sources: &[PathBuf]) -> Result<Vec<String>> {
2526        let wanted = validate_attachments(sources)?;
2527        if task.unfiled && task.attachments.is_empty() {
2528            // Not stored yet: the directory is created under the id's
2529            // reservation and keeps the id taken until the record lands.
2530            let names = std::cell::RefCell::new(Vec::new());
2531            self.reserve_id(
2532                task,
2533                |t| {
2534                    if self.id_in_use(&t.id, true)? {
2535                        return Ok(false);
2536                    }
2537                    *names.borrow_mut() = self.copy_attachments(t, &wanted)?;
2538                    Ok(true)
2539                },
2540                |_| {},
2541                false,
2542            )?;
2543            return Ok(names.into_inner());
2544        }
2545        self.copy_attachments(task, &wanted)
2546    }
2547
2548    /// Copy `wanted` into `task`'s attachment directory (see [`Queue::attach`]).
2549    fn copy_attachments(
2550        &self,
2551        task: &mut Task,
2552        wanted: &[(&PathBuf, &str)],
2553    ) -> Result<Vec<String>> {
2554        let dir = self.attachments_dir(&task.id);
2555        let existed = dir.is_dir();
2556        std::fs::create_dir_all(&dir).with_context(|| format!("create {}", dir.display()))?;
2557        let mut created: Vec<PathBuf> = Vec::new();
2558        let mut names = Vec::new();
2559        let mut copy_all = || -> Result<()> {
2560            for (src, name) in wanted {
2561                let (stored, path) = copy_new(&dir, src, name)?;
2562                created.push(path);
2563                names.push(stored);
2564            }
2565            Ok(())
2566        };
2567        if let Err(e) = copy_all() {
2568            for path in &created {
2569                let _ = std::fs::remove_file(path);
2570            }
2571            if !existed {
2572                let _ = std::fs::remove_dir(&dir);
2573            }
2574            return Err(e);
2575        }
2576        task.attachments.extend(names.iter().cloned());
2577        Ok(names)
2578    }
2579
2580    /// [`Queue::attach`] then [`Queue::put`], undoing the copies when the
2581    /// record cannot be written. Without the undo the files sit in
2582    /// `<id>.attachments/` with no task pointing at them.
2583    ///
2584    /// Only what this call copied is removed (the names `attach` returned,
2585    /// and the directory itself only when it did not exist before and is
2586    /// empty), never an attachment an earlier save recorded. `task` is rolled
2587    /// back too, and the error the caller sees is `put`'s own. This relies on
2588    /// a failed `put` leaving the stored record untouched, which its
2589    /// write-then-rename guarantees.
2590    pub fn attach_and_put(&self, task: &mut Task, sources: &[PathBuf]) -> Result<Vec<String>> {
2591        if task.unfiled && task.attachments.is_empty() {
2592            return self.attach_and_file(task, sources);
2593        }
2594        let dir = self.attachments_dir(&task.id);
2595        let existed = dir.is_dir();
2596        let before = task.attachments.len();
2597        let names = self.attach(task, sources)?;
2598        if let Err(e) = self.put(task) {
2599            for name in &names {
2600                let _ = std::fs::remove_file(dir.join(name));
2601            }
2602            if !existed {
2603                let _ = std::fs::remove_dir(&dir);
2604            }
2605            task.attachments.truncate(before);
2606            return Err(e);
2607        }
2608        Ok(names)
2609    }
2610
2611    /// [`Queue::attach_and_put`] for a task not yet stored: the attachment
2612    /// directory is created under the id's reservation, and a candidate whose
2613    /// directory already exists is taken.
2614    fn attach_and_file(&self, task: &mut Task, sources: &[PathBuf]) -> Result<Vec<String>> {
2615        let wanted = validate_attachments(sources)?;
2616        let before = task.attachments.len();
2617        let names = std::cell::RefCell::new(Vec::new());
2618        let result = self.file_with(
2619            task,
2620            |t| {
2621                if self.id_in_use(&t.id, true)? {
2622                    return Ok(false);
2623                }
2624                *names.borrow_mut() = self.copy_attachments(t, &wanted)?;
2625                Ok(true)
2626            },
2627            |t| {
2628                let dir = self.attachments_dir(&t.id);
2629                for name in names.borrow().iter() {
2630                    let _ = std::fs::remove_file(dir.join(name));
2631                }
2632                // The directory did not exist when the id was reserved.
2633                let _ = std::fs::remove_dir(&dir);
2634                t.attachments.truncate(before);
2635            },
2636        );
2637        result.map(|()| names.into_inner())
2638    }
2639
2640    /// Absolute paths of `task`'s attachments, whatever shape this queue's
2641    /// root has. Absolute because the prompt hands them to an agent whose
2642    /// working directory is somewhere else entirely.
2643    pub fn attachment_paths(&self, task: &Task) -> Vec<PathBuf> {
2644        let dir = self.attachments_dir(&task.id);
2645        task.attachments
2646            .iter()
2647            .map(|n| {
2648                let p = dir.join(n);
2649                std::path::absolute(&p).unwrap_or(p)
2650            })
2651            .collect()
2652    }
2653
2654    /// Write a task, atomically, so a daemon killed mid-write leaves the
2655    /// previous state readable rather than a truncated file.
2656    ///
2657    /// Runs already recorded on disk that `task` does not carry are kept, not
2658    /// dropped: `magi run --task` links a run into a task from another
2659    /// process ([`Queue::link_run`]) while a daemon may hold a snapshot taken
2660    /// before it, and writing that snapshot back whole would erase the link.
2661    /// Nothing ever removes a run from a task, so the union loses nothing.
2662    pub fn put(&self, task: &mut Task) -> Result<()> {
2663        if task.unfiled {
2664            // A new task never merges into a record that has its id.
2665            return self.file_with(task, |t| self.plain_filing_hook(t), |_| {});
2666        }
2667        let _lock = self.lock_task(&task.id)?;
2668        self.put_unlocked(task)
2669    }
2670
2671    /// Write `task` only if no task with its id exists yet; `Ok(false)` when
2672    /// one does. Unlike [`Queue::put`] it never replaces a record, so a
2673    /// producer with a deterministic id cannot rewind a task that has since
2674    /// started running or finished.
2675    pub fn create_new(&self, task: &mut Task) -> Result<bool> {
2676        let _lock = self.lock_task(&task.id)?;
2677        if path_exists(&self.path_of(&task.id))? {
2678            return Ok(false);
2679        }
2680        self.write_record(task)?;
2681        task.unfiled = false;
2682        Ok(true)
2683    }
2684
2685    /// [`Queue::put`] for a caller already holding [`Queue::lock_task`].
2686    fn put_unlocked(&self, task: &mut Task) -> Result<()> {
2687        self.merge_stored(task);
2688        if let Some(boundary) = task.reassignments.last() {
2689            let stored = self.get(&task.id)?;
2690            anyhow::ensure!(
2691                task.reassignments == stored.reassignments
2692                    && task.repo == stored.repo
2693                    && task.runs.get(..boundary.run_boundary)
2694                        == stored.runs.get(..boundary.run_boundary),
2695                "historical repository execution cannot be restarted; reload the task"
2696            );
2697        }
2698        self.write_record(task)
2699    }
2700
2701    /// Save an exact-run recovery pin only if its admitted owner snapshot is current.
2702    pub(crate) fn commit_base_recovery(
2703        &self,
2704        task: &mut Task,
2705        expected: &serde_json::Value,
2706    ) -> Result<()> {
2707        let _lock = self.lock_task(&task.id)?;
2708        anyhow::ensure!(
2709            serde_json::to_value(self.get(&task.id)?)? == *expected,
2710            "task changed during base recovery; inspect the pending authorization"
2711        );
2712        // Retain the ordinary merge evidence when replacing an earlier decision pin.
2713        self.put_unlocked(task)
2714    }
2715
2716    /// Commit one validated reassignment under the task write lock.
2717    pub(crate) fn commit_reassignment(&self, task: &mut Task, expected: &Task) -> Result<()> {
2718        let _lock = self.lock_task(&task.id)?;
2719        let stored = self.get(&task.id)?;
2720        anyhow::ensure!(
2721            serde_json::to_value(&stored)? == serde_json::to_value(expected)?
2722                && stored.reassignments.len() + 1 == task.reassignments.len()
2723                && stored.repo == task.reassignments.last().expect("new boundary").from
2724                && stored.runs == task.runs,
2725            "task changed during reassignment; retry after inspecting it"
2726        );
2727        self.write_record(task)
2728    }
2729
2730    /// Fold the stored record of `task`'s id into `task` (updates only).
2731    fn merge_stored(&self, task: &mut Task) {
2732        if let Ok(mut stored) = read_path(&self.path_of(&task.id)) {
2733            stored.import_chat_notice();
2734            if stored.reassignments.len() > task.reassignments.len() {
2735                // An older writer may contribute evidence, but cannot restore
2736                // old execution selections, status, or runs across the boundary.
2737                let stale = std::mem::replace(task, stored.clone());
2738                for answer in stale.answers {
2739                    if !task.answers.contains(&answer) {
2740                        task.answers.push(answer);
2741                    }
2742                }
2743            }
2744            for key in &stored.base_recovery_requests {
2745                if !task.base_recovery_requests.contains(key) {
2746                    task.base_recovery_requests.push(key.clone());
2747                }
2748            }
2749            for receipt in &stored.repair_grants {
2750                if !task
2751                    .repair_grants
2752                    .iter()
2753                    .any(|r| r.request.request == receipt.request.request)
2754                {
2755                    // A pre-grant snapshot cannot drop the atomic queue reservation.
2756                    task.repair_grants.push(receipt.clone());
2757                    task.resume_override = stored.resume_override.clone();
2758                    task.status = stored.status;
2759                    task.hold_source = stored.hold_source;
2760                    task.hold_reason = stored.hold_reason.clone();
2761                    task.held_at = stored.held_at;
2762                }
2763            }
2764            for receipt in &stored.repair_reconciliations {
2765                if !task.repair_reconciliations.contains(receipt) {
2766                    // A pre-reconciliation snapshot must preserve the recovery's
2767                    // exact-run queue pin and release state with its receipt.
2768                    task.repair_reconciliations.push(receipt.clone());
2769                    task.resume_override = stored.resume_override.clone();
2770                    task.status = stored.status;
2771                    task.hold_source = stored.hold_source;
2772                    task.hold_reason = stored.hold_reason.clone();
2773                    task.held_at = stored.held_at;
2774                }
2775            }
2776            task.superseded_resumes.extend(stored.superseded_resumes);
2777            task.dispatched_resumes.extend(stored.dispatched_resumes);
2778            if task.status != TaskStatus::Running
2779                && let Some(pin) = &stored.resume_override
2780                && !pin.question_id.is_empty()
2781                && let Some(run) = &pin.pinned_run
2782                && task.resume_override.as_ref().is_none_or(|next| {
2783                    next.question_id != pin.question_id || next.pinned_run != pin.pinned_run
2784                })
2785            {
2786                task.superseded_resumes
2787                    .insert(pin.question_id.clone(), run.clone());
2788            }
2789            // A writer holding an older task snapshot must never erase or
2790            // rewrite proof that a chat command already committed its effect.
2791            for (id, receipt) in stored.decision_effects {
2792                task.decision_effects.insert(id, receipt);
2793            }
2794            if !task.decision_effects.is_empty() {
2795                task.schema = task.schema.max(SCHEMA);
2796            }
2797            // The task's message chat is recorded once and never rewound or
2798            // dropped by a writer holding an older snapshot.
2799            if task.chat.is_none() {
2800                task.chat = stored.chat.clone();
2801            }
2802            for key in stored.chat_notices {
2803                if !task.chat_notices.contains(&key) {
2804                    task.chat_notices.push(key);
2805                }
2806            }
2807            for failure in stored.startup_failures {
2808                task.record_startup_failure(failure);
2809            }
2810            for run in stored.runs {
2811                if !task.runs.contains(&run) {
2812                    task.runs.push(run);
2813                }
2814            }
2815            for p in stored.passes {
2816                if !task
2817                    .passes
2818                    .iter()
2819                    .any(|q| q.run == p.run && q.pass_index == p.pass_index)
2820                {
2821                    task.passes.push(p);
2822                }
2823            }
2824            // A completion notice already recorded is never rewound by an
2825            // older snapshot: that would report the same state twice.
2826            if let Some(n) = stored.chat_notice
2827                && task.chat_notice.as_ref().is_none_or(|mine| mine.at < n.at)
2828            {
2829                task.chat_notice = Some(n);
2830            }
2831        }
2832    }
2833
2834    /// Audit-only update; caller holds the task write lock and claim. Preserve
2835    /// timestamps, controls and notification state while appending startup evidence.
2836    pub(crate) fn write_startup_history(&self, task: &Task) -> Result<()> {
2837        let path = self.path_of(&task.id);
2838        let tmp = path.with_extension("json.tmp");
2839        std::fs::write(&tmp, serde_json::to_vec_pretty(task)?)?;
2840        std::fs::rename(tmp, path)?;
2841        Ok(())
2842    }
2843
2844    /// Stamp and write `task` atomically; the caller holds the id's lock.
2845    fn write_record(&self, task: &mut Task) -> Result<()> {
2846        task.import_chat_notice();
2847        task.updated_at = Timestamp::now();
2848        std::fs::create_dir_all(&self.root)
2849            .with_context(|| format!("create {}", self.root.display()))?;
2850        let body = serde_json::to_string_pretty(task).context("serialize task")?;
2851        let path = self.path_of(&task.id);
2852        let tmp = path.with_extension("json.tmp");
2853        std::fs::write(&tmp, &body).with_context(|| format!("write {}", tmp.display()))?;
2854        std::fs::rename(&tmp, &path).with_context(|| format!("replace {}", path.display()))?;
2855        // A machine hold is news for the notification centre, filed beside
2856        // this queue (`<home>/queue` -> `<home>/notifications`) rather than
2857        // through a process-global, so a queue in a temp directory notifies
2858        // into that directory.
2859        if let (Some(notice), Some(home)) = (
2860            crate::notices::task_held(task),
2861            self.root.parent().filter(|p| !p.as_os_str().is_empty()),
2862        ) {
2863            crate::notices::raise_in(home, notice);
2864        }
2865        Ok(())
2866    }
2867
2868    /// Change the task `id` in place: read it inside its write lock, let `f`
2869    /// edit it, and write it back only when `f` returns `true`. The check a
2870    /// caller makes in `f` therefore sees the record as stored now, not a
2871    /// snapshot taken before another writer got in. Returns whether it wrote.
2872    pub fn modify(&self, id: &str, f: impl FnOnce(&mut Task) -> bool) -> Result<bool> {
2873        let id = self.resolve_id(id)?;
2874        let _lock = self.lock_task(&id)?;
2875        let mut task = self.get(&id)?;
2876        if !f(&mut task) {
2877            return Ok(false);
2878        }
2879        self.put_unlocked(&mut task)?;
2880        Ok(true)
2881    }
2882
2883    /// Append `run` to the runs of the task `id` (or an unambiguous prefix),
2884    /// leaving everything else about it alone — see [`Task::link_run`]. Read
2885    /// and written back in one breath, because [`Queue::put`] replaces the
2886    /// whole record. Returns the task as stored.
2887    pub fn link_run(&self, id: &str, run: &str) -> Result<Task> {
2888        let id = self.resolve_id(id)?;
2889        // Read inside the lock, so the record written back is the current one
2890        // and a daemon's write cannot slip between the read and the write.
2891        let _lock = self.lock_task(&id)?;
2892        let mut task = self.get(&id)?;
2893        if task.link_run(run) {
2894            self.put_unlocked(&mut task)?;
2895        }
2896        Ok(task)
2897    }
2898
2899    /// Exclusive right to rewrite task `id`'s record, held until the guard
2900    /// drops. Every writer ([`Queue::put`], [`Queue::link_run`]) takes it, so
2901    /// a process linking a run and the daemon saving a transition are
2902    /// serialized instead of last-writer-wins. An old lock may be broken only
2903    /// after its writer is confirmed dead (legacy tokens without a PID retain
2904    /// age-based recovery). Not the claim lock (`<id>.lock`), held for a
2905    /// whole run.
2906    pub(crate) fn lock_task(&self, id: &str) -> Result<TaskLock> {
2907        std::fs::create_dir_all(&self.root)
2908            .with_context(|| format!("create {}", self.root.display()))?;
2909        let path = self.root.join(format!("{id}.write-lock"));
2910        let started = std::time::Instant::now();
2911        let retry = crate::lock_file::Retry::task_write(started + TASK_LOCK_STALE);
2912        let marker_retry = crate::lock_file::Retry::new(Some(started + TASK_LOCK_STALE));
2913        loop {
2914            match retry.create(&path) {
2915                Ok(mut file) => {
2916                    use std::io::Write;
2917                    let token = owner_token();
2918                    if let Err(e) = file.write_all(token.as_bytes()) {
2919                        drop(file);
2920                        let _ = std::fs::remove_file(&path);
2921                        return Err(e).with_context(|| format!("lock {}", path.display()));
2922                    }
2923                    return Ok(TaskLock { path, token });
2924                }
2925                Err(e) if e.kind() == std::io::ErrorKind::AlreadyExists => {
2926                    // Content first, then age: a lock replaced in between
2927                    // reads fresh, never stale.
2928                    let judged = std::fs::read_to_string(&path).ok();
2929                    let broken = judged
2930                        .filter(|_| older_than_stale(&path))
2931                        .is_some_and(|judged| break_stale_with(&path, &judged, marker_retry));
2932                    // A break that does not happen (marker busy, recovery
2933                    // exhausted) is a wait like any other, so it meets the
2934                    // same deadline instead of spinning forever.
2935                    if !broken {
2936                        if started.elapsed() > TASK_LOCK_STALE {
2937                            bail!("could not lock task {id}");
2938                        }
2939                        std::thread::sleep(std::time::Duration::from_millis(15));
2940                    }
2941                }
2942                Err(e) => return Err(e).with_context(|| format!("lock {}", path.display())),
2943            }
2944        }
2945    }
2946
2947    /// Load a task by id or unambiguous id prefix.
2948    pub fn get(&self, id: &str) -> Result<Task> {
2949        let resolved = self.resolve_id(id)?;
2950        read_path(&self.path_of(&resolved))
2951    }
2952
2953    /// Remove a task, and the claim lock that belongs to it.
2954    ///
2955    /// `in_flight` comes from the caller — a live daemon's heartbeat naming
2956    /// this task — because the task's own `running` status cannot answer the
2957    /// question. A daemon killed mid-competition leaves the status at
2958    /// `running` and an orphaned `.lock` behind, and a guard that trusted
2959    /// either would make the task undeletable for good: the phone showed
2960    /// exactly that, refusing a task whose daemon had been gone for an hour.
2961    ///
2962    /// So the lock is removed with the task rather than respected. Any lock
2963    /// still there once no live daemon claims the task is by definition stale,
2964    /// and leaving it would make a deleted task look claimed to
2965    /// [`Queue::claim`] and to whoever reads the directory.
2966    ///
2967    /// A deletion is deliberate, so whatever was `blocked` on the id is
2968    /// resolved, not held: a `<id>.removed` tombstone is written first (it
2969    /// is what tells [`missing_blockers`] and the daemon's resolver that this
2970    /// id was deleted on purpose, so a pass that races this call cannot
2971    /// mistake it for a vanished dependency), the record is deleted (the
2972    /// tombstone is taken back if that fails), and then each dependent is
2973    /// rewritten under its claim - see [`Queue::release_dependents_of`].
2974    /// Best-effort for the dependents: one claimed by something else right
2975    /// now, or whose write fails, is released silently by
2976    /// `crate::daemon::resolve_blockers` (or `crate::triage::run_once`) on
2977    /// its next pass, because the tombstone is still there. It does not fail
2978    /// this removal.
2979    ///
2980    /// `questions` is the store [`missing_blockers`] checks a `blocked_by` id
2981    /// against - the same store the caller already resolves `id`'s own home
2982    /// from, passed in rather than reopened here so a test queue at an
2983    /// explicit root never reads the operator's real questions directory.
2984    pub fn remove(&self, id: &str, in_flight: bool, questions: &Questions) -> Result<Removal> {
2985        self.remove_with_receipt(id, in_flight, questions, None)
2986    }
2987
2988    /// Atomically retain the deleted task as the receipt for this triage inquiry.
2989    pub(crate) fn discard_triage(
2990        &self,
2991        id: &str,
2992        questions: &Questions,
2993        inquiry: &str,
2994    ) -> Result<Removal> {
2995        self.remove_with_receipt(id, false, questions, Some(inquiry))
2996    }
2997
2998    pub(crate) fn triage_discard_applied(&self, id: &str, inquiry: &str) -> Result<bool> {
2999        let path = self
3000            .root
3001            .join("triage-discard")
3002            .join(format!("{inquiry}.json"));
3003        let bytes = match std::fs::read(path) {
3004            Ok(bytes) => bytes,
3005            Err(e) if e.kind() == std::io::ErrorKind::NotFound => return Ok(false),
3006            Err(e) => return Err(e.into()),
3007        };
3008        let receipt: Task = serde_json::from_slice(&bytes)?;
3009        Ok(receipt.id == id && !self.path_of(id).exists())
3010    }
3011
3012    fn remove_with_receipt(
3013        &self,
3014        id: &str,
3015        in_flight: bool,
3016        questions: &Questions,
3017        inquiry: Option<&str>,
3018    ) -> Result<Removal> {
3019        let resolved = self.resolve_id(id)?;
3020        if in_flight {
3021            bail!("task {resolved} is being run by a live daemon right now");
3022        }
3023        let receipt = inquiry.map(|q| self.root.join("triage-discard").join(format!("{q}.json")));
3024        if let Some(path) = &receipt {
3025            std::fs::create_dir_all(path.parent().expect("receipt directory"))?;
3026        }
3027        self.write_tombstone(&resolved)?;
3028        if let Err(e) = self.remove_record_with_attachments(&resolved, |p| match &receipt {
3029            Some(path) => std::fs::rename(p, path),
3030            None => std::fs::remove_file(p),
3031        }) {
3032            // A record that is still there was not deleted: take the marker
3033            // back. One already gone keeps it, so the deletion still reads
3034            // as deliberate.
3035            if self.path_of(&resolved).exists() {
3036                let _ = std::fs::remove_file(self.tombstone_path(&resolved));
3037            }
3038            return Err(e);
3039        }
3040        let (released, still_blocked) = self.release_dependents_of(&resolved, questions);
3041        Ok(Removal {
3042            id: resolved,
3043            released,
3044            still_blocked,
3045        })
3046    }
3047
3048    /// Path of the marker saying task `id` was deleted on purpose. Not a
3049    /// `*.json`, so [`Queue::list`] and [`Queue::revision`] never see it.
3050    fn tombstone_path(&self, id: &str) -> PathBuf {
3051        self.root.join(format!("{id}.removed"))
3052    }
3053
3054    fn write_tombstone(&self, id: &str) -> Result<()> {
3055        let path = self.tombstone_path(id);
3056        let tmp = self.root.join(format!("{id}.removed.tmp"));
3057        std::fs::write(&tmp, b"")
3058            .and_then(|()| std::fs::rename(&tmp, &path))
3059            .with_context(|| format!("write {}", path.display()))
3060    }
3061
3062    /// Was `id` deleted through [`Queue::remove`] (and is its record gone)?
3063    /// A live record always wins: a tombstone never makes an existing task
3064    /// look deleted.
3065    fn was_deleted(&self, id: &str) -> bool {
3066        self.tombstone_path(id).is_file() && !self.path_of(id).exists()
3067    }
3068
3069    /// Apply [`Task::dependency_deleted`] to `task` for every `blocked_by` id
3070    /// that [`Queue::remove`] deleted. Returns those ids. The caller holds
3071    /// the task's claim and saves it.
3072    pub fn apply_deleted_blockers(&self, task: &mut Task, questions: &Questions) -> Vec<String> {
3073        let deleted = deleted_blockers(self, questions, &task.blocked_by);
3074        deleted
3075            .into_iter()
3076            .filter(|id| task.dependency_deleted(id))
3077            .collect()
3078    }
3079
3080    /// Record, as a fixed-wording info notice, that `dependent` stopped
3081    /// waiting on the deleted task `deleted`. Best-effort and beside the
3082    /// queue, like the hold notice [`Queue::put`] files.
3083    pub fn note_dependency_deleted(&self, dependent: &Task, deleted: &str) {
3084        let Some(home) = self.root.parent().filter(|p| !p.as_os_str().is_empty()) else {
3085            return;
3086        };
3087        let ja = crate::lang::is_japanese(&crate::lang::of_repo(&dependent.repo));
3088        let waiting = dependent.status == TaskStatus::Blocked;
3089        let message = match (ja, waiting) {
3090            (true, false) => format!(
3091                "タスク {} は、待っていた {} が削除されたため待機を解除し、元の状態に戻しました",
3092                dependent.short(),
3093                short(deleted)
3094            ),
3095            (true, true) => format!(
3096                "タスク {} は、待っていた {} が削除されたため、残りの依存を待っています",
3097                dependent.short(),
3098                short(deleted)
3099            ),
3100            (false, false) => format!(
3101                "Task {} stopped waiting on {} because it was deleted, and returned to its previous state",
3102                dependent.short(),
3103                short(deleted)
3104            ),
3105            (false, true) => format!(
3106                "Task {} stopped waiting on {} because it was deleted, and is still waiting on its other dependencies",
3107                dependent.short(),
3108                short(deleted)
3109            ),
3110        };
3111        crate::notices::raise_in(
3112            home,
3113            crate::notices::Notice::info(
3114                &format!("unblocked:{}:{}", dependent.id, deleted),
3115                message,
3116            )
3117            .link(crate::notices::Link::Task {
3118                id: dependent.id.clone(),
3119            }),
3120        );
3121    }
3122
3123    /// Resolve every `blocked` task naming `dependency` (just deleted) with
3124    /// [`Task::dependency_deleted`]. Returns the ids released to another
3125    /// status and those that remain `blocked` on something else. Each
3126    /// dependent is re-read inside its claim, never written from a stale copy.
3127    fn release_dependents_of(
3128        &self,
3129        dependency: &str,
3130        questions: &Questions,
3131    ) -> (Vec<String>, Vec<String>) {
3132        let (mut released, mut still_blocked) = (Vec::new(), Vec::new());
3133        for listed in self.list() {
3134            if listed.status != TaskStatus::Blocked || !listed.blocked_by.iter().any(|b| {
3135                matches!(crate::queue::dependency(self, questions, b), Dependency::Deleted(id) if id == dependency)
3136            }) {
3137                continue;
3138            }
3139            let Ok(_claim) = self.claim(&listed.id) else {
3140                continue;
3141            };
3142            let Ok(mut task) = self.get(&listed.id) else {
3143                continue;
3144            };
3145            let references: Vec<String> = task.blocked_by.iter().filter(|id| {
3146                matches!(crate::queue::dependency(self, questions, id), Dependency::Deleted(full) if full == dependency)
3147            }).cloned().collect();
3148            if references.is_empty() {
3149                continue;
3150            }
3151            for reference in references {
3152                task.dependency_deleted(&reference);
3153            }
3154            if self.put(&mut task).is_err() {
3155                continue;
3156            }
3157            self.note_dependency_deleted(&task, dependency);
3158            if task.status == TaskStatus::Blocked {
3159                still_blocked.push(task.id.clone());
3160            } else {
3161                released.push(task.id.clone());
3162            }
3163        }
3164        (released, still_blocked)
3165    }
3166
3167    /// The attachment-and-record half of [`Queue::remove`]. `remove_record` is
3168    /// how the record file is deleted; production passes `remove_file`, and a
3169    /// test passes a failing one to prove the attachments come back.
3170    fn remove_record_with_attachments(
3171        &self,
3172        resolved: &str,
3173        remove_record: impl FnOnce(&Path) -> std::io::Result<()>,
3174    ) -> Result<()> {
3175        // Neither step may strand the other. The attachments are set aside by a
3176        // rename (cheap, and undone if the record cannot be removed), then the
3177        // record goes, and only then is the set-aside directory deleted for
3178        // real. A failure before the record is gone loses nothing; a failure
3179        // after it leaves at most an orphan `.removing` directory, which the
3180        // next removal sweeps.
3181        self.sweep_removed_attachments();
3182        let attachments = self.attachments_dir(resolved);
3183        let aside = self.root.join(format!("{resolved}.attachments.removing"));
3184        let moved = match std::fs::rename(&attachments, &aside) {
3185            Ok(()) => true,
3186            Err(e) if e.kind() == std::io::ErrorKind::NotFound => false,
3187            Err(e) => {
3188                return Err(e).with_context(|| format!("remove {}", attachments.display()));
3189            }
3190        };
3191        let path = self.path_of(resolved);
3192        if let Err(e) = remove_record(&path) {
3193            if moved {
3194                let _ = std::fs::rename(&aside, &attachments);
3195            }
3196            return Err(e).with_context(|| format!("remove {}", path.display()));
3197        }
3198        if moved {
3199            if let Err(e) = std::fs::remove_dir_all(&aside) {
3200                tracing::warn!("leftover attachments {}: {e}", aside.display());
3201            }
3202        }
3203        let lock = self.lock_path(resolved);
3204        if let Err(e) = std::fs::remove_file(&lock) {
3205            if e.kind() != std::io::ErrorKind::NotFound {
3206                return Err(e).with_context(|| format!("remove {}", lock.display()));
3207            }
3208        }
3209        Ok(())
3210    }
3211
3212    /// Delete `*.attachments.removing` directories a previous [`Queue::remove`]
3213    /// could not finish deleting. The task record is already gone by then, so
3214    /// the id no longer resolves and the removal cannot be retried by name;
3215    /// every later removal sweeps them instead. A directory whose record still
3216    /// exists belongs to a removal in progress and is left alone. Best-effort.
3217    fn sweep_removed_attachments(&self) {
3218        let Ok(entries) = std::fs::read_dir(&self.root) else {
3219            return;
3220        };
3221        for entry in entries.flatten() {
3222            let name = entry.file_name();
3223            let name = name.to_string_lossy();
3224            let Some(id) = name.strip_suffix(".attachments.removing") else {
3225                continue;
3226            };
3227            // A record still on disk means a removal is mid-flight (or about
3228            // to roll back): the directory is its to delete or restore.
3229            if !self.path_of(id).exists() {
3230                if let Err(e) = std::fs::remove_dir_all(entry.path()) {
3231                    tracing::warn!("leftover attachments {}: {e}", entry.path().display());
3232                }
3233            }
3234        }
3235        self.sweep_tombstones();
3236    }
3237
3238    /// Delete `*.removed` markers that are no longer needed: the record is
3239    /// gone, no task's `blocked_by` names the id, and the marker is older than
3240    /// [`TOMBSTONE_GRACE`]. The age is what makes this safe against a
3241    /// concurrent writer: the task list read here can be stale, so a dependent
3242    /// that was just blocked on an id (a conductor applying a decision while a
3243    /// removal is under way) would otherwise lose the marker and be held as a
3244    /// vanished dependency. A marker whose record still exists belongs to a
3245    /// removal in progress and is never touched.
3246    fn sweep_tombstones(&self) {
3247        let Ok(entries) = std::fs::read_dir(&self.root) else {
3248            return;
3249        };
3250        let tasks = self.list();
3251        for entry in entries.flatten() {
3252            let name = entry.file_name();
3253            let name = name.to_string_lossy();
3254            let Some(id) = name.strip_suffix(".removed") else {
3255                continue;
3256            };
3257            if self.path_of(id).exists()
3258                || tasks.iter().any(|t| {
3259                    t.blocked_by
3260                        .iter()
3261                        .any(|b| id.starts_with(b) || id.ends_with(b))
3262                })
3263            {
3264                continue;
3265            }
3266            let old = entry
3267                .metadata()
3268                .and_then(|m| m.modified())
3269                .ok()
3270                .and_then(|m| m.elapsed().ok())
3271                .is_some_and(|age| age >= TOMBSTONE_GRACE);
3272            if old {
3273                let _ = std::fs::remove_file(entry.path());
3274            }
3275        }
3276    }
3277
3278    /// Path of the claim lock for a task. One definition, so `claim` and
3279    /// `remove` cannot end up naming different files.
3280    fn lock_path(&self, id: &str) -> PathBuf {
3281        self.root.join(format!("{id}.lock"))
3282    }
3283
3284    /// Every task on disk, highest priority first and newest first within a
3285    /// priority. This is what `magi task list` and `GET /api/queue` print, so
3286    /// a raised priority has to move a task here the moment it is saved, not
3287    /// only in [`Queue::next_runnable`]'s own ordering - the operator reading
3288    /// the backlog and the loop about to drain it must agree on what "first"
3289    /// means. Every existing task defaults to priority 0, so this is a no-op
3290    /// change from the old newest-first order for a queue nobody has
3291    /// reprioritised.
3292    ///
3293    /// Unreadable files are skipped rather than fatal: one corrupt task must
3294    /// not take the queue - or the web UI, or an unattended daemon - down
3295    /// with it.
3296    pub fn list(&self) -> Vec<Task> {
3297        let mut tasks: Vec<Task> = std::fs::read_dir(&self.root)
3298            .into_iter()
3299            .flatten()
3300            .flatten()
3301            .map(|e| e.path())
3302            .filter(|p| p.extension().is_some_and(|x| x == "json"))
3303            .filter_map(|p| read_path(&p).ok())
3304            .collect();
3305        tasks.sort_unstable_by(|a, b| b.priority.cmp(&a.priority).then_with(|| b.id.cmp(&a.id)));
3306        tasks
3307    }
3308
3309    /// Task files [`Queue::list`] skips because they cannot be parsed (a
3310    /// newer schema, a torn write). A guard that looks a task up by scanning
3311    /// the list must treat any of these as "the task might be there".
3312    pub fn unreadable(&self) -> Vec<PathBuf> {
3313        std::fs::read_dir(&self.root)
3314            .into_iter()
3315            .flatten()
3316            .flatten()
3317            .map(|e| e.path())
3318            .filter(|p| p.extension().is_some_and(|x| x == "json"))
3319            .filter(|p| read_path(p).is_err())
3320            .collect()
3321    }
3322
3323    /// Runs that a later attempt at the same task replaced, mapped to the id
3324    /// of the attempt that replaced them.
3325    ///
3326    /// A task keeps its attempts in order, and the deck showed them as two
3327    /// cards with the same title and no hint which was which: yukimemi asked
3328    /// why `stalled` and `blocked` appeared twice for one task, and the
3329    /// answer - "those are two tries, and the second one exists because of a
3330    /// bug since fixed" - was not on the screen anywhere.
3331    ///
3332    /// Read from the queue rather than stored on the run, because the
3333    /// ordering is the queue's fact: a `RunState` has no idea another attempt
3334    /// happened after it.
3335    pub fn superseded(&self) -> HashMap<String, String> {
3336        let mut by = HashMap::new();
3337        for task in self.list() {
3338            for earlier in &task.runs {
3339                if let Some(later) = task.successor_of(earlier) {
3340                    by.insert(earlier.clone(), later.clone());
3341                }
3342            }
3343        }
3344        by
3345    }
3346
3347    /// Whether `run` is an earlier attempt a later one replaced, and if so
3348    /// the id of that later attempt.
3349    ///
3350    /// Same walk as [`Queue::superseded`], narrowed to one run: a run detail
3351    /// page asks about exactly one run at a time, and this keeps that call
3352    /// site from building (and discarding) the whole map's `HashMap` just to
3353    /// read one entry out of it.
3354    pub fn superseded_by(&self, run: &str) -> Option<String> {
3355        for task in self.list() {
3356            if task.runs.iter().any(|r| r == run) {
3357                return task.successor_of(run).cloned();
3358            }
3359        }
3360        None
3361    }
3362
3363    /// The task's own most recent attempt, when `run` belongs to that task
3364    /// but is not already that attempt.
3365    ///
3366    /// Distinct from [`Queue::superseded_by`], which names only the very
3367    /// next attempt: a chain of retries (A superseded by B superseded by C)
3368    /// leaves an older run pointing at an intermediate one that may itself
3369    /// be unresolved, and a run's own detail page needs to know where the
3370    /// task's story currently stands - the chain's current head, C - not an
3371    /// attempt in the middle of it that a client would otherwise have to
3372    /// walk to by hand.
3373    pub fn latest_attempt(&self, run: &str) -> Option<String> {
3374        for task in self.list() {
3375            if task.runs.iter().any(|r| r == run) {
3376                return task.runs.last().filter(|last| **last != run).cloned();
3377            }
3378        }
3379        None
3380    }
3381
3382    /// The task a daemon should run next, or `None` when the queue is idle.
3383    ///
3384    /// Upgrade resumes first, then highest priority and oldest id first.
3385    /// See [`dispatch_order`] for the durable ordering rule.
3386    pub fn next_runnable(&self) -> Option<Task> {
3387        let mut runnable: Vec<Task> = self
3388            .list()
3389            .into_iter()
3390            .filter(|t| t.status.runnable())
3391            .collect();
3392        runnable.sort_unstable_by(dispatch_order);
3393        runnable.into_iter().next()
3394    }
3395
3396    /// Take exclusive ownership of a task.
3397    ///
3398    /// The lock is a `create_new` file next to the task, which is atomic on
3399    /// every platform magi targets. It exists so two daemons - or a daemon and
3400    /// a human running `magi run` - cannot drive one task into two competing
3401    /// runs. The returned guard releases on drop, including on panic.
3402    pub fn claim(&self, id: &str) -> Result<Claim> {
3403        std::fs::create_dir_all(&self.root)
3404            .with_context(|| format!("create {}", self.root.display()))?;
3405        let path = self.lock_path(id);
3406        let retry = crate::lock_file::Retry::new(None);
3407        match retry.create(&path) {
3408            Ok(mut f) => {
3409                use std::io::Write as _;
3410                // Best effort: the pid is for the human looking at a stale lock.
3411                let _ = writeln!(f, "{}", std::process::id());
3412                Ok(Claim { path })
3413            }
3414            Err(e) if e.kind() == std::io::ErrorKind::AlreadyExists => {
3415                bail!("task {id} is already claimed ({} exists)", path.display())
3416            }
3417            Err(e) => Err(e).with_context(|| format!("lock {}", path.display())),
3418        }
3419    }
3420
3421    /// Expand an id prefix to exactly one task id.
3422    pub fn resolve_id(&self, prefix: &str) -> Result<String> {
3423        if !prefix.is_empty()
3424            && prefix != "."
3425            && prefix != ".."
3426            && !prefix.contains(['/', '\\'])
3427            && self.path_of(prefix).is_file()
3428        {
3429            return Ok(prefix.to_owned());
3430        }
3431        let ids = record_ids(&self.root, "json")?;
3432        match resolve_reference(prefix, ids.iter().map(String::as_str)) {
3433            Reference::Found(id) => Ok(id),
3434            Reference::Missing => bail!("no task matches `{prefix}`"),
3435            Reference::Ambiguous => bail!("`{prefix}` matches multiple tasks"),
3436        }
3437    }
3438
3439    /// Change detection token for the queue.
3440    ///
3441    /// Combines file names and modification times of all task files in the
3442    /// queue, so adding, modifying, or deleting any task — even an older one —
3443    /// moves the revision and notifies connected clients via the change stream.
3444    /// Returns 0 when the queue is completely empty.
3445    pub fn revision(&self) -> u64 {
3446        self.revision_excluding(&std::collections::BTreeSet::new())
3447    }
3448
3449    /// [`Queue::revision`] ignoring the files of the named task ids, for a
3450    /// caller that tracks those tasks' content some other way.
3451    pub fn revision_excluding(&self, skip: &std::collections::BTreeSet<String>) -> u64 {
3452        use std::hash::{Hash as _, Hasher as _};
3453
3454        let mut entries: Vec<(String, u64)> = std::fs::read_dir(&self.root)
3455            .into_iter()
3456            .flatten()
3457            .flatten()
3458            .filter(|e| e.path().extension().is_some_and(|ext| ext == "json"))
3459            .filter(|e| {
3460                let path = e.path();
3461                !path
3462                    .file_stem()
3463                    .is_some_and(|stem| skip.contains(stem.to_string_lossy().as_ref()))
3464            })
3465            .filter_map(|e| {
3466                let name = e.file_name().to_string_lossy().into_owned();
3467                let mtime = e
3468                    .metadata()
3469                    .ok()?
3470                    .modified()
3471                    .ok()?
3472                    .duration_since(std::time::UNIX_EPOCH)
3473                    .ok()?
3474                    .as_millis() as u64;
3475                Some((name, mtime))
3476            })
3477            .collect();
3478
3479        if entries.is_empty() {
3480            return 0;
3481        }
3482
3483        entries.sort_unstable();
3484        let mut hasher = std::hash::DefaultHasher::new();
3485        for (name, mtime) in &entries {
3486            name.hash(&mut hasher);
3487            mtime.hash(&mut hasher);
3488        }
3489        let h = hasher.finish();
3490        if h == 0 { 1 } else { h }
3491    }
3492}
3493
3494/// How long a deletion marker is kept after its record is gone, even with
3495/// nothing referencing it. See [`Queue::sweep_tombstones`].
3496const TOMBSTONE_GRACE: std::time::Duration = std::time::Duration::from_secs(3600);
3497
3498/// What [`Queue::remove`] did, beyond deleting the named task's own file.
3499#[derive(Debug, Clone)]
3500pub struct Removal {
3501    /// The id actually removed - `id` expanded from a prefix, if it was one.
3502    pub id: String,
3503    /// Every task that was `blocked` on [`Removal::id`] and left the block
3504    /// (back to the status it interrupted) because that was its only
3505    /// remaining dependency.
3506    pub released: Vec<String>,
3507    /// Every task that named [`Removal::id`] and is still `blocked` on
3508    /// another dependency.
3509    pub still_blocked: Vec<String>,
3510}
3511
3512/// Exclusive ownership of a task, released on drop.
3513#[derive(Debug)]
3514pub struct Claim {
3515    path: PathBuf,
3516}
3517
3518impl Drop for Claim {
3519    fn drop(&mut self) {
3520        let _ = std::fs::remove_file(&self.path);
3521    }
3522}
3523
3524/// The first line of a task, trimmed to a title. Used when the caller gives a
3525/// body but no title, which is the normal case for an agent piping a file in.
3526pub fn title_from(instruction: &str, max: usize) -> String {
3527    let Some(line) = first_line(instruction) else {
3528        return "(empty task)".to_owned();
3529    };
3530    if line.chars().count() <= max {
3531        return line.to_owned();
3532    }
3533    let head: String = line.chars().take(max.saturating_sub(1)).collect();
3534    format!("{head}…")
3535}
3536
3537/// The first non-blank line, whatever it is. A markdown heading is the
3538/// task's own summary - agents pipe in `# Rework the config loader` and mean
3539/// exactly that - so it is preferred over the prose beneath it rather than
3540/// skipped as decoration. Leading list and heading markers are stripped
3541/// because they are syntax, not words. `None` when nothing is left.
3542pub(crate) fn first_line(instruction: &str) -> Option<&str> {
3543    let line = instruction
3544        .lines()
3545        .map(str::trim)
3546        .find(|l| !l.is_empty())?
3547        .trim_start_matches(['#', '-', '*', '>', ' '])
3548        .trim();
3549    (!line.is_empty()).then_some(line)
3550}
3551
3552fn read_path(path: &Path) -> Result<Task> {
3553    let body = std::fs::read_to_string(path).with_context(|| format!("read {}", path.display()))?;
3554    let task: Task =
3555        serde_json::from_str(&body).with_context(|| format!("parse {}", path.display()))?;
3556    // Greater-than, not not-equal: every field added since schema 1 carries
3557    // `#[serde(default)]`, so an older task has nothing to say about it and
3558    // defaulting is exactly as good a reading as a value that build never had
3559    // a chance to write. Only a schema *ahead* of this build - a meaning it
3560    // cannot possibly know - is refused rather than guessed at.
3561    if task.schema > SCHEMA {
3562        bail!(
3563            "task {} was written by a different magi (schema {}, this build \
3564             speaks {SCHEMA})",
3565            task.id,
3566            task.schema
3567        );
3568    }
3569    Ok(task)
3570}
3571
3572/// Resolution shared by queue lookups and dependency inventories. Exact ids
3573/// win; otherwise both the CLI prefix and displayed suffix are supported.
3574#[derive(Debug, PartialEq, Eq)]
3575pub(crate) enum Reference {
3576    Found(String),
3577    Missing,
3578    Ambiguous,
3579}
3580
3581pub(crate) fn resolve_reference<'a>(id: &str, ids: impl Iterator<Item = &'a str>) -> Reference {
3582    let mut hits = Vec::new();
3583    for candidate in ids {
3584        if candidate == id {
3585            return Reference::Found(candidate.to_owned());
3586        }
3587        if candidate.starts_with(id) || candidate.ends_with(id) {
3588            hits.push(candidate);
3589        }
3590    }
3591    match hits.as_slice() {
3592        [] => Reference::Missing,
3593        [one] => Reference::Found((*one).to_owned()),
3594        _ => Reference::Ambiguous,
3595    }
3596}
3597
3598/// Read names, not deserialized records: list() intentionally skips corrupt
3599/// and future-schema records, which still exist and must keep their waiters.
3600pub(crate) fn record_ids(root: &Path, extension: &str) -> Result<Vec<String>> {
3601    let entries = match std::fs::read_dir(root) {
3602        Ok(entries) => entries,
3603        Err(e) if e.kind() == std::io::ErrorKind::NotFound => return Ok(Vec::new()),
3604        Err(e) => return Err(e.into()),
3605    };
3606    let mut ids = Vec::new();
3607    for entry in entries {
3608        let path = entry?.path();
3609        if path.extension().is_some_and(|e| e == extension)
3610            && let Some(id) = path.file_stem().and_then(|s| s.to_str())
3611        {
3612            ids.push(id.to_owned());
3613        }
3614    }
3615    Ok(ids)
3616}
3617
3618/// Unknown and ambiguous dependencies stay waiting; neither is evidence that
3619/// the operator deleted a prerequisite or needs to supply its replacement.
3620#[derive(Debug, PartialEq, Eq)]
3621pub enum Dependency {
3622    /// Existing task record, with its canonical id; its contents may be unreadable.
3623    Task(String),
3624    /// Existing question record, with its canonical id.
3625    Question(String),
3626    /// Explicitly removed task, identified by its tombstone.
3627    Deleted(String),
3628    /// No matching record or tombstone after a successful inventory read.
3629    Missing,
3630    /// More than one record matches the reference.
3631    Ambiguous,
3632    /// The inventory cannot currently be read, so existence is unknown.
3633    Unknown,
3634}
3635
3636/// Resolve against authoritative task, question and deletion record names.
3637pub fn dependency(queue: &Queue, questions: &Questions, id: &str) -> Dependency {
3638    let (Ok(tasks), Ok(qs), Ok(removed)) = (
3639        record_ids(queue.root(), "json"),
3640        record_ids(questions.root(), "json"),
3641        record_ids(queue.root(), "removed"),
3642    ) else {
3643        return Dependency::Unknown;
3644    };
3645    // Include tombstones in ambiguity checks: a reused suffix must never
3646    // release a waiter on a different, still-live task.
3647    let mut ids = tasks
3648        .iter()
3649        .chain(qs.iter())
3650        .chain(removed.iter())
3651        .cloned()
3652        .collect::<Vec<_>>();
3653    ids.sort();
3654    ids.dedup();
3655    match resolve_reference(id, ids.iter().map(String::as_str)) {
3656        Reference::Found(id) if tasks.contains(&id) => Dependency::Task(id),
3657        Reference::Found(id) if qs.contains(&id) => Dependency::Question(id),
3658        Reference::Found(id) if queue.was_deleted(&id) => Dependency::Deleted(id),
3659        Reference::Found(_) => Dependency::Unknown,
3660        Reference::Missing => Dependency::Missing,
3661        Reference::Ambiguous => Dependency::Ambiguous,
3662    }
3663}
3664
3665/// Canonicalize only proven dependencies, preserving unknown legacy references.
3666pub fn normalize_blockers(queue: &Queue, questions: &Questions, ids: &mut [String]) {
3667    for id in ids {
3668        if let Dependency::Task(full) | Dependency::Question(full) | Dependency::Deleted(full) =
3669            dependency(queue, questions, id)
3670        {
3671            *id = full;
3672        }
3673    }
3674}
3675
3676/// Live queue facts for decision and deputy prompts. Historical hold reasons
3677/// and question text are claims, never an inventory of existing prerequisites.
3678pub fn dependency_facts(queue: &Queue, questions: &Questions) -> String {
3679    let inventory = crate::blockers::Inventory::load(queue, questions);
3680    let mut text = String::from(
3681        "Current authoritative queue (historical missing-task claims may be stale; unreadable or ambiguous references must keep waiting):\n",
3682    );
3683    match record_ids(queue.root(), "json") {
3684        Ok(ids) => {
3685            for id in ids {
3686                match queue.get(&id) {
3687                    Ok(task) => text.push_str(&format!(
3688                        "{}: {}; blocked_by={:?}; chain={:?}\n",
3689                        task.id,
3690                        task.status.as_str(),
3691                        task.blocked_by,
3692                        inventory.waits_on(&task)
3693                    )),
3694                    Err(_) => text.push_str(&format!("{id}: exists, state unreadable\n")),
3695                }
3696            }
3697        }
3698        Err(_) => text.push_str("Queue inventory unreadable: existence is unknown.\n"),
3699    }
3700    text
3701}
3702
3703/// Only a successful directory scan with no matching record proves absence.
3704pub fn missing_blockers(
3705    queue: &Queue,
3706    questions: &Questions,
3707    blocked_by: &[String],
3708) -> Vec<String> {
3709    blocked_by
3710        .iter()
3711        .filter(|id| dependency(queue, questions, id) == Dependency::Missing)
3712        .cloned()
3713        .collect()
3714}
3715
3716/// Return the original references, so legacy short ids are removed by the
3717/// same Task transition as full ids.
3718pub fn deleted_blockers(
3719    queue: &Queue,
3720    questions: &Questions,
3721    blocked_by: &[String],
3722) -> Vec<String> {
3723    blocked_by
3724        .iter()
3725        .filter(|id| matches!(dependency(queue, questions, id), Dependency::Deleted(_)))
3726        .cloned()
3727        .collect()
3728}
3729
3730/// The `hold_reason` text for a task quarantined because one or more of its
3731/// `blocked_by` ids no longer exist. Shared by `crate::daemon::resolve_blockers`,
3732/// `crate::triage::run_once`, and [`Queue::remove`]'s own dependent
3733/// quarantine, so the three call sites read as the same event to an operator
3734/// looking at `magi task show` rather than three different wordings for it.
3735///
3736/// Names the full original `blocked_by` list, not just `missing` - a task
3737/// quarantined here can also have named a dependency that was still
3738/// perfectly valid, and [`Task::hold_machine`] clears `blocked_by` on the way
3739/// in, so this text is the only place that information survives for an
3740/// operator deciding whether to release the task outright.
3741pub fn missing_blocker_hold_reason(blocked_by: &[String], missing: &[String]) -> String {
3742    missing_blocker_hold_reason_in(blocked_by, missing, "en")
3743}
3744
3745/// [`missing_blocker_hold_reason`] in `language` (Japanese, else English).
3746pub fn missing_blocker_hold_reason_in(
3747    blocked_by: &[String],
3748    missing: &[String],
3749    language: &str,
3750) -> String {
3751    if crate::lang::is_japanese(language) {
3752        format!(
3753            "{} を待っていましたが、{} はディスク上に存在しません - `magi task triage` を参照",
3754            blocked_by.join(", "),
3755            missing.join(", "),
3756        )
3757    } else {
3758        format!(
3759            "blocked on {} but {} no longer exist(s) on disk - see `magi task triage`",
3760            blocked_by.join(", "),
3761            missing.join(", "),
3762        )
3763    }
3764}
3765
3766/// The last dash-separated part of an id, the form people say aloud.
3767pub fn short(id: &str) -> &str {
3768    id.split('-').next_back().unwrap_or(id)
3769}
3770
3771fn new_id() -> String {
3772    let stamp = jiff::Zoned::now().strftime("%Y%m%d-%H%M%S");
3773    let seed = crate::rng::entropy();
3774    format!("{stamp}-{:04x}", (seed ^ (seed >> 32)) & 0xffff)
3775}
3776
3777#[cfg(test)]
3778mod tests {
3779    #[test]
3780    fn reassignment_clears_repository_bound_execution_selections() {
3781        let mut task = Task::new(
3782            "move".into(),
3783            "evidence".into(),
3784            "old".into(),
3785            Source::Human,
3786        );
3787        task.review_branch = Some("old-review".into());
3788        task.review_instruction = Some("old criteria".into());
3789        task.pr_recovery = Some(crate::pr_recovery::Selection {
3790            url: "https://example.invalid/pull/1".into(),
3791            branch: "old-pr".into(),
3792            head: "head".into(),
3793            source_head: None,
3794            source_run: None,
3795            source_proof: None,
3796            disposition: None,
3797            instruction: "old criteria".into(),
3798            approved_at: Timestamp::now(),
3799        });
3800        task.replacement = Some(crate::merge_decision::Replacement {
3801            question: "owner".into(),
3802            run: "old-run".into(),
3803            pr: "https://example.invalid/pull/1".into(),
3804            agent: "worker".into(),
3805            context: "evidence".into(),
3806        });
3807        task.resume_override = Some(OperatorResume {
3808            question_id: "old-question".into(),
3809            at: Timestamp::now(),
3810            conductor_rehold: None,
3811            forced: true,
3812            pinned_run: Some("old-run".into()),
3813        });
3814        task.interrupt = true;
3815        task.reassign_repository("new".into(), "test");
3816        assert!(task.review_branch.is_none());
3817        assert!(task.review_instruction.is_none());
3818        assert!(task.pr_recovery.is_none());
3819        assert!(task.replacement.is_none());
3820        assert!(task.resume_override.is_none());
3821        assert!(!task.interrupt);
3822        assert!(task.fresh_start);
3823        assert_eq!(task.instruction, "evidence");
3824    }
3825
3826    #[test]
3827    fn explicit_resumption_is_not_invented_for_legacy_or_automatic_release() {
3828        let t = Task::new(
3829            "retry".into(),
3830            "do it".into(),
3831            PathBuf::from("."),
3832            Source::Human,
3833        );
3834        let mut value = serde_json::to_value(&t).unwrap();
3835        for field in ["resumption", "resumption_history", "operator_decided_at"] {
3836            value.as_object_mut().unwrap().remove(field);
3837        }
3838        value["schema"] = serde_json::json!(15);
3839        let mut legacy: Task = serde_json::from_value(value).unwrap();
3840        legacy.hold_machine(Some("automatic retry".into()));
3841        legacy.release();
3842        assert!(legacy.resumption.is_none());
3843        assert!(legacy.resumption_history.is_empty());
3844        assert!(legacy.operator_decided_at.is_none());
3845        legacy.release_operator("cli", None);
3846        legacy.start("run".into());
3847        let reloaded: Task =
3848            serde_json::from_str(&serde_json::to_string(&legacy).unwrap()).unwrap();
3849        assert!(reloaded.resume_override.is_none());
3850        assert_eq!(reloaded.resumption.as_ref().unwrap().generation, 1);
3851    }
3852
3853    #[test]
3854    fn merge_over_lets_the_later_choice_win_and_keeps_the_rest() {
3855        let mut base = RunOverrides {
3856            merge: Some("pr".to_owned()),
3857            candidates: Some(3),
3858            ..RunOverrides::default()
3859        };
3860        base.merge_over(&RunOverrides {
3861            merge: Some("none".to_owned()),
3862            seed: Some(7),
3863            ..RunOverrides::default()
3864        });
3865        assert_eq!(base.merge.as_deref(), Some("none"));
3866        assert_eq!(base.candidates, Some(3));
3867        assert_eq!(base.seed, Some(7));
3868    }
3869
3870    #[test]
3871    fn an_already_landed_task_is_done_with_its_attempt_refunded() {
3872        let mut t = task("relanded");
3873        t.attempts = 1;
3874        t.status = TaskStatus::Running;
3875        t.already_landed("already in main as 0e368de");
3876        assert_eq!(t.status, TaskStatus::Done);
3877        assert_eq!(t.attempts, 0);
3878        assert!(t.hold_reason.is_none());
3879        assert_eq!(t.last_error.as_deref(), Some("already in main as 0e368de"));
3880    }
3881
3882    #[test]
3883    fn missing_blocker_reason_follows_the_language() {
3884        let b = vec!["a".to_owned()];
3885        let en = missing_blocker_hold_reason_in(&b, &b, "en");
3886        assert_eq!(en, missing_blocker_hold_reason(&b, &b));
3887        assert!(en.starts_with("blocked on a"));
3888        assert!(missing_blocker_hold_reason_in(&b, &b, "ja").contains("存在しません"));
3889        assert_eq!(missing_blocker_hold_reason_in(&b, &b, "de"), en);
3890    }
3891
3892    use super::*;
3893
3894    #[test]
3895    fn triage_applied_survives_release_and_old_records_read_as_empty() {
3896        let mut t = Task::new(
3897            "t".to_owned(),
3898            "i".to_owned(),
3899            PathBuf::from("r"),
3900            Source::Human,
3901        );
3902        t.mark_triage_applied("q1");
3903        t.mark_triage_applied("q1");
3904        t.hold_machine(Some("x".to_owned()));
3905        t.release();
3906        assert_eq!(t.triage_applied, ["q1"]);
3907        assert!(t.triage_applied("q1") && !t.triage_applied("q2"));
3908
3909        let mut v = serde_json::to_value(&t).unwrap();
3910        v.as_object_mut().unwrap().remove("triage_applied");
3911        let old: Task = serde_json::from_value(v).unwrap();
3912        assert!(old.triage_applied.is_empty());
3913    }
3914
3915    #[test]
3916    fn task_counts_of_empty_is_all_zero() {
3917        assert_eq!(TaskCounts::of(&[]), TaskCounts::default());
3918    }
3919
3920    #[test]
3921    fn task_counts_of_tallies_every_status() {
3922        let mut queued = Task::new(
3923            "q".to_owned(),
3924            "i".to_owned(),
3925            PathBuf::from("."),
3926            Source::Human,
3927        );
3928        queued.status = TaskStatus::Queued;
3929        let mut running = queued.clone();
3930        running.status = TaskStatus::Running;
3931        let mut done = queued.clone();
3932        done.status = TaskStatus::Done;
3933        let mut failed = queued.clone();
3934        failed.status = TaskStatus::Failed;
3935        let mut held = queued.clone();
3936        held.status = TaskStatus::Held;
3937        let mut blocked = queued.clone();
3938        blocked.status = TaskStatus::Blocked;
3939
3940        let mut parked = queued.clone();
3941        parked.status = TaskStatus::Parked;
3942
3943        let counts = TaskCounts::of(&[
3944            queued,
3945            running,
3946            done.clone(),
3947            done,
3948            failed,
3949            held,
3950            blocked,
3951            parked,
3952        ]);
3953        assert_eq!(
3954            counts,
3955            TaskCounts {
3956                queued: 1,
3957                running: 1,
3958                done: 2,
3959                failed: 1,
3960                held: 1,
3961                blocked: 1,
3962                parked: 1,
3963            }
3964        );
3965    }
3966
3967    #[test]
3968    fn task_implementers_persist_normalized_without_losing_history() {
3969        let (_dir, q) = queue();
3970        let mut t = task("keep me");
3971        t.hold_manual(Some("waiting".into()));
3972        t.runs.push("earlier-run".into());
3973        t.attachments.push("reference.txt".into());
3974        let cfg: crate::config::Config =
3975            toml::from_str("[[agents]]\nid = 'mock'\nkind = 'command'\ncommand = ['true']\n")
3976                .unwrap();
3977        q.put(&mut t).unwrap();
3978        let original = serde_json::to_value(&t).unwrap();
3979        for n in [2, 1, 2] {
3980            t.set_implementers(n, &cfg).unwrap();
3981            q.put(&mut t).unwrap();
3982            t = q.get(&t.id).unwrap();
3983            assert_eq!(t.implementers(), Some(usize::from(n)));
3984            assert_eq!(t.solo, n == 1);
3985            if n == 1 {
3986                assert!(t.overrides.is_none());
3987            }
3988            let mut actual = serde_json::to_value(&t).unwrap();
3989            for field in ["solo", "overrides", "updated_at"] {
3990                actual[field] = original[field].clone();
3991            }
3992            assert_eq!(actual, original);
3993        }
3994        t.overrides.as_mut().unwrap().judges = Some(2);
3995        t.set_implementers(1, &cfg).unwrap();
3996        assert_eq!(t.overrides.as_ref().unwrap().judges, Some(2));
3997        assert_eq!(t.overrides.as_ref().unwrap().candidates, None);
3998    }
3999
4000    #[test]
4001    fn task_implementers_old_records_keep_inheritance_until_changed() {
4002        let mut value = serde_json::to_value(task("old task")).unwrap();
4003        value.as_object_mut().unwrap().remove("solo");
4004        value.as_object_mut().unwrap().remove("overrides");
4005        let mut old: Task = serde_json::from_value(value).unwrap();
4006        assert_eq!(old.implementers(), None);
4007        old.set_implementers(1, &crate::config::Config::default())
4008            .unwrap();
4009        assert!(old.solo);
4010        assert!(old.overrides.is_none());
4011    }
4012
4013    #[test]
4014    fn task_implementers_reject_invalid_counts_and_states() {
4015        let cfg = crate::config::Config::default();
4016        let mut t = task("unchanged");
4017        for n in [0, 4, 255] {
4018            assert!(t.set_implementers(n, &cfg).is_err());
4019        }
4020        for status in [
4021            TaskStatus::Running,
4022            TaskStatus::Done,
4023            TaskStatus::Failed,
4024            TaskStatus::Blocked,
4025            TaskStatus::Parked,
4026        ] {
4027            t.status = status;
4028            let before = serde_json::to_value(&t).unwrap();
4029            assert!(t.set_implementers(1, &cfg).is_err());
4030            assert_eq!(serde_json::to_value(&t).unwrap(), before);
4031        }
4032    }
4033
4034    /// A queue of its own, with no process-global state - which is the point of
4035    /// `Queue::at`, and why these can run in parallel.
4036    fn queue() -> (tempfile::TempDir, Queue) {
4037        let dir = tempfile::tempdir().unwrap();
4038        let q = Queue::at(dir.path().join("queue"));
4039        (dir, q)
4040    }
4041
4042    #[test]
4043    fn base_recovery_commit_retains_decision_and_superseded_resume_evidence() {
4044        let (_dir, q) = queue();
4045        let mut original = task("base recovery");
4046        original
4047            .decision_effects
4048            .insert("old-effect".into(), "receipt".into());
4049        original
4050            .dispatched_resumes
4051            .insert("dispatched".into(), "prior-run".into());
4052        original.resume_override = Some(OperatorResume {
4053            question_id: "prior-decision".into(),
4054            at: Timestamp::now(),
4055            conductor_rehold: None,
4056            forced: true,
4057            pinned_run: Some("retained-run".into()),
4058        });
4059        q.put(&mut original).unwrap();
4060        let expected = serde_json::to_value(&original).unwrap();
4061        let mut recovered = original.clone();
4062        recovered.base_recovery_requests.push("chat/request".into());
4063        recovered
4064            .resume_override
4065            .as_mut()
4066            .unwrap()
4067            .question_id
4068            .clear();
4069        q.commit_base_recovery(&mut recovered, &expected).unwrap();
4070        let saved = q.get(&original.id).unwrap();
4071        assert_eq!(saved.decision_effects, original.decision_effects);
4072        assert_eq!(saved.dispatched_resumes, original.dispatched_resumes);
4073        assert_eq!(
4074            saved
4075                .superseded_resumes
4076                .get("prior-decision")
4077                .map(String::as_str),
4078            Some("retained-run")
4079        );
4080        assert_eq!(saved.base_recovery_requests, ["chat/request"]);
4081        assert!(saved.resume_override.unwrap().question_id.is_empty());
4082        assert!(q.commit_base_recovery(&mut recovered, &expected).is_err());
4083    }
4084
4085    #[test]
4086    fn a_stale_write_does_not_drop_the_recorded_task_chat() {
4087        let (_dir, q) = queue();
4088        let mut stale = task("chat");
4089        q.put(&mut stale).unwrap();
4090        let mut fresh = q.get(&stale.id).unwrap();
4091        fresh.chat = Some("talk-1".to_owned());
4092        q.put(&mut fresh).unwrap();
4093        q.put(&mut stale).unwrap();
4094        assert_eq!(q.get(&stale.id).unwrap().chat.as_deref(), Some("talk-1"));
4095    }
4096
4097    #[test]
4098    fn putting_a_machine_held_task_files_a_notification_beside_the_queue() {
4099        let dir = tempfile::tempdir().unwrap();
4100        let q = Queue::at(dir.path().join("queue"));
4101        let mut t = task("held");
4102        q.put(&mut t).unwrap();
4103        assert_eq!(
4104            crate::notices::Notices::at(dir.path().join("notifications"))
4105                .list()
4106                .len(),
4107            0
4108        );
4109        t.hold_machine(Some("out of attempts".to_owned()));
4110        q.put(&mut t).unwrap();
4111        let listed = crate::notices::Notices::at(dir.path().join("notifications")).list();
4112        assert_eq!(listed.len(), 1);
4113        assert!(listed[0].message.contains("out of attempts"));
4114    }
4115
4116    fn task(title: &str) -> Task {
4117        Task::new(
4118            title.to_owned(),
4119            format!("do {title}"),
4120            PathBuf::from("."),
4121            Source::Human,
4122        )
4123    }
4124
4125    #[test]
4126    fn attempt_limit_inherits_old_records_and_controls_failure() {
4127        let mut t = task("budget");
4128        let mut old = serde_json::to_value(&t).unwrap();
4129        old.as_object_mut().unwrap().remove("attempt_limit");
4130        old["schema"] = serde_json::json!(15);
4131        let legacy: Task = serde_json::from_value(old).unwrap();
4132        assert_eq!(legacy.attempt_limit, None);
4133        assert_eq!(legacy.effective_attempt_limit(2), 2);
4134        t.attempts = 2;
4135        t.change_attempt_limit(NonZeroUsize::new(3)).unwrap();
4136        t.fail("retry", 1);
4137        assert_eq!(t.status, TaskStatus::Failed);
4138        t.attempts = 3;
4139        t.fail("stop", 10);
4140        assert_eq!(t.status, TaskStatus::Held);
4141        t.change_attempt_limit(None).unwrap();
4142        assert_eq!(t.status, TaskStatus::Held);
4143        assert_eq!(t.attempts, 3);
4144        t.fail("inherit", 4);
4145        assert_eq!(t.status, TaskStatus::Failed);
4146        for status in [
4147            TaskStatus::Running,
4148            TaskStatus::Done,
4149            TaskStatus::Failed,
4150            TaskStatus::Blocked,
4151            TaskStatus::Parked,
4152        ] {
4153            t.status = status;
4154            assert!(t.change_attempt_limit(NonZeroUsize::new(1)).is_err());
4155            assert_eq!(t.attempt_limit, None);
4156        }
4157    }
4158
4159    #[test]
4160    fn earlier_attempts_is_every_recorded_run_and_agrees_with_the_display() {
4161        let mut t = task("retried");
4162        assert!(
4163            t.earlier_attempts().is_empty(),
4164            "a first attempt takes nothing over"
4165        );
4166        t.runs = vec!["aaaa".to_owned(), "bbbb".to_owned()];
4167        assert_eq!(t.earlier_attempts(), ["aaaa", "bbbb"]);
4168        // What the web note shows and what a takeover acts on are one rule.
4169        assert_eq!(t.successor_of("aaaa"), Some(&"bbbb".to_owned()));
4170        assert_eq!(t.successor_of("bbbb"), None);
4171        assert_eq!(t.successor_of("zzzz"), None);
4172    }
4173
4174    #[test]
4175    fn resumed_runs_are_superseded_only_after_their_last_occurrence() {
4176        let (_dir, q) = queue();
4177        let mut t = task("resumed");
4178        for (runs, successor) in [
4179            (vec!["aaaa", "aaaa"], None),
4180            (vec!["aaaa", "bbbb", "aaaa"], None),
4181            (vec!["aaaa", "aaaa", "bbbb"], Some("bbbb")),
4182            (vec!["aaaa", "bbbb", "aaaa", "cccc"], Some("cccc")),
4183        ] {
4184            t.runs = runs.into_iter().map(str::to_owned).collect();
4185            q.put(&mut t).unwrap();
4186
4187            assert_eq!(t.successor_of("aaaa").map(String::as_str), successor);
4188            assert_eq!(q.superseded_by("aaaa").as_deref(), successor);
4189            assert_eq!(q.superseded().get("aaaa").map(String::as_str), successor);
4190        }
4191    }
4192
4193    #[test]
4194    fn superseded_by_names_the_next_attempt_and_none_for_the_last() {
4195        let (_dir, q) = queue();
4196        let mut t = task("retried");
4197        t.runs = vec!["aaaa".to_owned(), "bbbb".to_owned(), "cccc".to_owned()];
4198        q.put(&mut t).unwrap();
4199
4200        assert_eq!(q.superseded_by("aaaa"), Some("bbbb".to_owned()));
4201        assert_eq!(q.superseded_by("bbbb"), Some("cccc".to_owned()));
4202        assert_eq!(
4203            q.superseded_by("cccc"),
4204            None,
4205            "the latest attempt replaces nothing"
4206        );
4207        assert_eq!(
4208            q.superseded_by("never-heard-of-it"),
4209            None,
4210            "a run belonging to no task on this queue is not superseded"
4211        );
4212
4213        let mut by = HashMap::new();
4214        by.insert("aaaa".to_owned(), "bbbb".to_owned());
4215        by.insert("bbbb".to_owned(), "cccc".to_owned());
4216        assert_eq!(
4217            q.superseded(),
4218            by,
4219            "the whole-map and single-run forms must agree"
4220        );
4221    }
4222
4223    #[test]
4224    fn superseded_attempts_is_empty_until_the_task_is_done() {
4225        let mut t = task("retried");
4226        t.runs = vec!["aaaa".to_owned(), "bbbb".to_owned()];
4227        t.status = TaskStatus::Failed;
4228        assert_eq!(
4229            t.superseded_attempts(true),
4230            &[] as &[String],
4231            "a task still retrying has no attempt yet that a later one made moot"
4232        );
4233
4234        t.status = TaskStatus::Running;
4235        assert_eq!(t.superseded_attempts(true), &[] as &[String]);
4236    }
4237
4238    #[test]
4239    fn superseded_attempts_names_every_run_before_the_one_that_succeeded() {
4240        let mut t = task("retried");
4241        t.runs = vec!["aaaa".to_owned(), "bbbb".to_owned(), "cccc".to_owned()];
4242        t.status = TaskStatus::Done;
4243        assert_eq!(
4244            t.superseded_attempts(true),
4245            &["aaaa".to_owned(), "bbbb".to_owned()],
4246            "cccc is the attempt whose success made the task done, and stays out"
4247        );
4248    }
4249
4250    #[test]
4251    fn superseded_attempts_is_empty_for_a_done_task_with_only_one_attempt() {
4252        let mut t = task("first try landed");
4253        t.runs = vec!["aaaa".to_owned()];
4254        t.status = TaskStatus::Done;
4255        assert_eq!(t.superseded_attempts(true), &[] as &[String]);
4256    }
4257
4258    #[test]
4259    fn superseded_attempts_is_empty_when_the_last_run_never_actually_succeeded() {
4260        // `succeed` is reachable directly - `magi task done`, its web
4261        // equivalent, and the conductor's `Recovery::Done` - on a task in
4262        // any status, including one whose last recorded attempt is itself
4263        // `Blocked`/`Failed`/anything but `Merged`/`Ready`. `runs.last()`
4264        // alone cannot tell that apart from the loop's own settle path, so
4265        // the caller's own read of that run's status is what decides this.
4266        let mut t = task("closed by hand after a manual merge");
4267        t.runs = vec!["aaaa".to_owned(), "bbbb".to_owned()];
4268        t.status = TaskStatus::Done;
4269        assert_eq!(
4270            t.superseded_attempts(false),
4271            &[] as &[String],
4272            "nothing here is provably why the task is done, so nothing is superseded"
4273        );
4274    }
4275
4276    #[test]
4277    fn latest_attempt_names_the_chain_s_current_head_not_just_the_next_one() {
4278        let (_dir, q) = queue();
4279        let mut t = task("retried twice");
4280        t.runs = vec!["aaaa".to_owned(), "bbbb".to_owned(), "cccc".to_owned()];
4281        q.put(&mut t).unwrap();
4282
4283        assert_eq!(
4284            q.latest_attempt("aaaa"),
4285            Some("cccc".to_owned()),
4286            "an old attempt points straight at the chain's current head, not the \
4287             next attempt in the middle of it"
4288        );
4289        assert_eq!(q.latest_attempt("bbbb"), Some("cccc".to_owned()));
4290        assert_eq!(
4291            q.latest_attempt("cccc"),
4292            None,
4293            "the latest attempt is not superseded by anything"
4294        );
4295        assert_eq!(
4296            q.latest_attempt("never-heard-of-it"),
4297            None,
4298            "a run belonging to no task on this queue is not superseded"
4299        );
4300    }
4301
4302    #[test]
4303    fn a_markdown_heading_is_the_title_not_decoration() {
4304        // A task file's heading is the summary its author already wrote, so it
4305        // beats the prose underneath. Getting this backwards was visible in the
4306        // first smoke test: a task titled "# Rework the config loader" listed
4307        // as "It re-reads the file on every lookup".
4308        assert_eq!(
4309            title_from("# Rework the config loader\n\nIt re-reads it.\n", 40),
4310            "Rework the config loader"
4311        );
4312        assert_eq!(title_from("- fix the thing", 40), "fix the thing");
4313        assert_eq!(title_from("> quoted task", 40), "quoted task");
4314        // Nothing usable at all still has to produce something printable.
4315        assert_eq!(title_from("   \n\n", 40), "(empty task)");
4316        assert_eq!(title_from("###\n", 40), "(empty task)");
4317    }
4318
4319    #[test]
4320    fn a_long_title_is_elided_by_characters_not_bytes() {
4321        // Byte truncation would split a multi-byte character and panic.
4322        let long = "課題".repeat(30);
4323        let title = title_from(&long, 10);
4324        assert_eq!(title.chars().count(), 10);
4325        assert!(title.ends_with('…'));
4326    }
4327
4328    #[test]
4329    fn priority_wins_and_ties_break_oldest_first() {
4330        let (_dir, q) = queue();
4331        let mut a = task("first");
4332        let mut b = task("second");
4333        let mut c = task("urgent");
4334        // Ids carry a timestamp, so force a known order.
4335        a.id = "20260101-000001-aaaa".to_owned();
4336        b.id = "20260101-000002-bbbb".to_owned();
4337        c.id = "20260101-000003-cccc".to_owned();
4338        c.priority = 5;
4339        for t in [&mut a, &mut b, &mut c] {
4340            q.put(t).unwrap();
4341        }
4342
4343        // Priority first...
4344        assert_eq!(q.next_runnable().unwrap().id, c.id);
4345        c.hold_machine(None);
4346        q.put(&mut c).unwrap();
4347        // ...then oldest, so a burst of new work cannot starve older work.
4348        assert_eq!(q.next_runnable().unwrap().id, a.id);
4349        assert_eq!(q.list().len(), 3, "b is still waiting its turn");
4350    }
4351
4352    #[test]
4353    fn a_blocked_task_never_starves_another_runnable_one() {
4354        let (_dir, q) = queue();
4355        let mut blocked = task("blocked");
4356        blocked.block(vec!["something".to_owned()], None);
4357        q.put(&mut blocked).unwrap();
4358
4359        let mut runnable = task("free to go");
4360        q.put(&mut runnable).unwrap();
4361
4362        let next = q.next_runnable().expect("a runnable task is still offered");
4363        assert_eq!(next.id, runnable.id);
4364    }
4365
4366    #[test]
4367    fn a_held_task_is_never_offered_to_the_loop() {
4368        let (_dir, q) = queue();
4369        let mut t = task("held");
4370        q.put(&mut t).unwrap();
4371        assert!(q.next_runnable().is_some());
4372
4373        t.hold_machine(None);
4374        q.put(&mut t).unwrap();
4375        assert!(
4376            q.next_runnable().is_none(),
4377            "a held task must wait for a human"
4378        );
4379
4380        // A failed task, by contrast, is exactly what the loop should retry.
4381        t.status = TaskStatus::Failed;
4382        q.put(&mut t).unwrap();
4383        assert!(q.next_runnable().is_some());
4384    }
4385
4386    #[test]
4387    fn attempts_are_capped_and_then_the_task_is_held() {
4388        let mut t = task("doomed");
4389
4390        t.start("run-1".to_owned());
4391        t.fail("gate red", 2);
4392        assert_eq!(t.status, TaskStatus::Failed, "one attempt of two: retry");
4393
4394        t.start("run-2".to_owned());
4395        t.fail("gate red", 2);
4396        assert_eq!(
4397            t.status,
4398            TaskStatus::Held,
4399            "out of attempts: stop spending money on it"
4400        );
4401        assert_eq!(t.runs, ["run-1", "run-2"]);
4402        assert_eq!(t.last_error.as_deref(), Some("gate red"));
4403        assert_eq!(
4404            t.hold_reason.as_deref(),
4405            Some("gate red"),
4406            "the hold must say why, not leave hold_reason null next to a \
4407             populated last_error"
4408        );
4409    }
4410
4411    #[test]
4412    fn handing_off_a_task_records_a_hold_reason_too() {
4413        let mut t = task("left a pull request");
4414        t.start("run-1".to_owned());
4415        t.handed_off("run ended with a pull request open [run run-1]");
4416        assert_eq!(t.status, TaskStatus::Held);
4417        assert_eq!(t.hold_source, Some(HoldSource::Machine));
4418        assert_eq!(
4419            t.hold_reason.as_deref(),
4420            Some("run ended with a pull request open [run run-1]")
4421        );
4422        assert_eq!(t.hold_reason, t.last_error);
4423    }
4424
4425    #[test]
4426    fn a_quota_stall_is_refunded_so_the_backlog_survives_the_night() {
4427        let mut t = task("stalled by quota");
4428
4429        t.start("run-1".to_owned());
4430        assert_eq!(t.attempts, 1);
4431        t.stall("judge-1, judge-2 out of quota");
4432        assert_eq!(
4433            t.attempts, 0,
4434            "a closed quota window must not spend the task's retry budget"
4435        );
4436        assert_eq!(t.status, TaskStatus::Failed, "the loop should retry it");
4437        assert_eq!(
4438            t.last_error.as_deref(),
4439            Some("judge-1, judge-2 out of quota")
4440        );
4441
4442        // A task can therefore stall all night and still get its real attempts
4443        // once the quota resets - which is the whole point.
4444        for _ in 0..20 {
4445            t.start("run-n".to_owned());
4446            t.stall("still out of quota");
4447        }
4448        t.start("run-real".to_owned());
4449        t.fail("gate red", 2);
4450        assert_eq!(
4451            t.status,
4452            TaskStatus::Failed,
4453            "the first attempt that was really judged is attempt one"
4454        );
4455    }
4456
4457    #[test]
4458    fn releasing_a_held_task_gives_it_a_real_second_chance() {
4459        let mut t = task("retry me");
4460        t.start("run-1".to_owned());
4461        t.fail("gate red", 1);
4462        assert_eq!(t.status, TaskStatus::Held);
4463
4464        t.release();
4465        assert_eq!(t.status, TaskStatus::Queued);
4466        // Without resetting attempts the next failure would re-hold at once,
4467        // and a release would be a no-op the operator cannot see.
4468        assert_eq!(t.attempts, 0);
4469        assert!(t.last_error.is_none());
4470        assert_eq!(
4471            t.runs.len(),
4472            1,
4473            "history is kept: attempts reset, evidence does not"
4474        );
4475    }
4476
4477    #[test]
4478    fn a_hold_reason_survives_and_a_release_clears_it() {
4479        let mut t = task("waiting on something else");
4480        t.hold_manual(Some(
4481            "waiting for 20260101-000000-aaaa to land first".to_owned(),
4482        ));
4483        assert_eq!(t.status, TaskStatus::Held);
4484        assert_eq!(
4485            t.hold_reason.as_deref(),
4486            Some("waiting for 20260101-000000-aaaa to land first")
4487        );
4488
4489        // Holding again with no reason must not erase the one already there.
4490        t.hold_manual(None);
4491        assert_eq!(
4492            t.hold_reason.as_deref(),
4493            Some("waiting for 20260101-000000-aaaa to land first"),
4494            "a bare re-hold keeps whatever a human already wrote down"
4495        );
4496
4497        // A hold with no reason at all is still an ordinary, allowed hold.
4498        let mut plain = task("no reason given");
4499        plain.hold_manual(None);
4500        assert_eq!(plain.status, TaskStatus::Held);
4501        assert!(plain.hold_reason.is_none());
4502
4503        t.release();
4504        assert_eq!(t.status, TaskStatus::Queued);
4505        assert!(
4506            t.hold_reason.is_none(),
4507            "a stale reason must not greet the next person who holds this task"
4508        );
4509    }
4510
4511    #[test]
4512    fn closing_a_held_task_as_done_clears_its_hold_reason_too() {
4513        // `done` can close a held task directly - neither `magi task done`
4514        // nor `POST /api/queue/{id}/done` requires a release first - so a
4515        // task held for "waiting on 3ed9" and then closed without ever being
4516        // released must not still read as waiting on it afterwards.
4517        let mut t = task("landed by hand while held");
4518        t.hold_manual(Some("waiting on 3ed9".to_owned()));
4519        assert_eq!(t.hold_reason.as_deref(), Some("waiting on 3ed9"));
4520
4521        t.succeed();
4522        assert_eq!(t.status, TaskStatus::Done);
4523        assert!(
4524            t.hold_reason.is_none(),
4525            "a done task cannot still be waiting on something"
4526        );
4527    }
4528
4529    #[test]
4530    fn holding_or_closing_a_blocked_task_clears_its_dependency_too() {
4531        // The web UI's "Hold" and "Mark done" buttons are both reachable on a
4532        // `blocked` task, not just on `queued`/`held` ones - neither requires
4533        // a release first. A task moved off `Blocked` that way must not still
4534        // carry the dependency it was waiting on: a dependency graph built
4535        // from `blocked_by` would otherwise keep drawing an edge for a task
4536        // that is not blocked on anything any more.
4537        let mut held = task("held straight out of blocked");
4538        held.block(
4539            vec!["20260101-000000-dead".to_owned()],
4540            Some("waiting on the migration script".to_owned()),
4541        );
4542        assert_eq!(held.status, TaskStatus::Blocked);
4543
4544        held.hold_manual(None);
4545        assert_eq!(held.status, TaskStatus::Held);
4546        assert!(
4547            held.blocked_by.is_empty(),
4548            "hold overrides the wait, same as release"
4549        );
4550        assert!(held.block_reason.is_none());
4551
4552        let mut done = task("closed straight out of blocked");
4553        done.block(
4554            vec!["20260101-000000-dead".to_owned()],
4555            Some("waiting on the migration script".to_owned()),
4556        );
4557        done.succeed();
4558        assert_eq!(done.status, TaskStatus::Done);
4559        assert!(
4560            done.blocked_by.is_empty(),
4561            "a done task cannot still be waiting on a dependency"
4562        );
4563        assert!(done.block_reason.is_none());
4564    }
4565
4566    #[test]
4567    fn a_blocked_task_is_never_offered_to_the_loop() {
4568        let mut t = task("blocked");
4569        assert!(t.status.runnable());
4570        t.block(
4571            vec!["dep-id".to_owned()],
4572            Some("waits on dep-id".to_owned()),
4573        );
4574        assert_eq!(t.status, TaskStatus::Blocked);
4575        assert!(!t.status.runnable());
4576        assert_eq!(TaskStatus::Blocked.as_str(), "blocked");
4577    }
4578
4579    #[test]
4580    fn unblocking_the_last_dependency_returns_the_task_to_queued() {
4581        let mut t = task("blocked on two");
4582        t.block(
4583            vec!["a".to_owned(), "b".to_owned()],
4584            Some("waits on a and b".to_owned()),
4585        );
4586
4587        t.unblock("a");
4588        assert_eq!(t.status, TaskStatus::Blocked, "b is still outstanding");
4589        assert_eq!(t.blocked_by, ["b"]);
4590
4591        t.unblock("b");
4592        assert_eq!(t.status, TaskStatus::Queued);
4593        assert!(t.blocked_by.is_empty());
4594        assert!(t.block_reason.is_none());
4595    }
4596
4597    #[test]
4598    fn unblocking_an_id_on_a_task_that_is_not_blocked_is_a_no_op() {
4599        let mut t = task("never blocked");
4600        t.unblock("whatever");
4601        assert_eq!(t.status, TaskStatus::Queued);
4602    }
4603
4604    #[test]
4605    fn a_held_task_blocked_on_a_question_returns_to_held_not_queued() {
4606        // The bug this guards: a task an operator (or `crate::triage`) has
4607        // deliberately held, once `crate::conduct` blocks it on a follow-up
4608        // question, must not silently re-enter the competition queue the
4609        // moment that question is answered - whatever the answer said.
4610        let mut t = task("held, then asked about");
4611        t.hold_machine(Some("out of attempts".to_owned()));
4612        assert_eq!(t.status, TaskStatus::Held);
4613
4614        t.block(vec!["q1".to_owned()], Some("what now?".to_owned()));
4615        assert_eq!(t.status, TaskStatus::Blocked);
4616
4617        t.record_answer("what now?".to_owned(), "leave it held".to_owned());
4618        t.unblock("q1");
4619        assert_eq!(t.status, TaskStatus::Held, "must restore, not requeue");
4620        assert_eq!(t.hold_reason.as_deref(), Some("out of attempts"));
4621        assert_eq!(t.hold_source, Some(HoldSource::Machine));
4622        assert!(t.blocked_from.is_none(), "consumed once restored");
4623    }
4624
4625    #[test]
4626    fn a_manually_held_task_blocked_on_a_question_returns_to_held() {
4627        let mut t = task("manually held, then asked about");
4628        t.hold_manual(Some("waiting on a dependency".to_owned()));
4629
4630        t.block(vec!["q1".to_owned()], None);
4631        t.unblock("q1");
4632
4633        assert_eq!(t.status, TaskStatus::Held);
4634        assert_eq!(t.hold_source, Some(HoldSource::Manual));
4635    }
4636
4637    #[test]
4638    fn re_blocking_an_already_blocked_task_keeps_the_original_blocked_from() {
4639        // A second `Task::block` call - `crate::conduct` adding a question on
4640        // top of an existing block - must not overwrite `blocked_from` with
4641        // `Blocked` itself, or the task would restore into itself.
4642        let mut t = task("held, blocked twice");
4643        t.hold_machine(None);
4644        t.block(vec!["q1".to_owned()], Some("first".to_owned()));
4645        t.block(
4646            vec!["q1".to_owned(), "q2".to_owned()],
4647            Some("second".to_owned()),
4648        );
4649
4650        t.unblock("q1");
4651        assert_eq!(t.status, TaskStatus::Blocked, "q2 still outstanding");
4652        t.unblock("q2");
4653        assert_eq!(t.status, TaskStatus::Held);
4654    }
4655
4656    #[test]
4657    fn unblocking_a_task_blocked_while_running_lands_on_queued_not_running() {
4658        // Whatever process was driving the run is gone by the time a
4659        // conductor's question about it gets answered - there is nothing left
4660        // to resume into.
4661        let mut t = task("blocked mid-run");
4662        t.start("run-1".to_owned());
4663        assert_eq!(t.status, TaskStatus::Running);
4664
4665        t.block(vec!["q1".to_owned()], None);
4666        t.unblock("q1");
4667        assert_eq!(t.status, TaskStatus::Queued);
4668    }
4669
4670    #[test]
4671    fn a_pre_schema_4_blocked_record_with_hold_evidence_restores_to_held() {
4672        // `blocked_from` is `None` for a record written before schema 4 (or,
4673        // equivalently, deserialized straight from an on-disk file that never
4674        // had the field). Held evidence surviving on the task - never cleared
4675        // by `block` - is the only way left to tell such a record apart from
4676        // one blocked straight out of `Queued`.
4677        let mut t = task("legacy record, held before it was blocked");
4678        t.hold_source = Some(HoldSource::Machine);
4679        t.hold_reason = Some("legacy hold reason".to_owned());
4680        t.status = TaskStatus::Blocked;
4681        t.blocked_by = vec!["q1".to_owned()];
4682        t.blocked_from = None;
4683
4684        t.unblock("q1");
4685        assert_eq!(t.status, TaskStatus::Held);
4686    }
4687
4688    #[test]
4689    fn a_pre_schema_4_blocked_record_with_no_hold_evidence_restores_to_queued() {
4690        let mut t = task("legacy record, ordinary dependency block");
4691        t.status = TaskStatus::Blocked;
4692        t.blocked_by = vec!["dep".to_owned()];
4693        t.blocked_from = None;
4694
4695        t.unblock("dep");
4696        assert_eq!(t.status, TaskStatus::Queued);
4697    }
4698
4699    #[test]
4700    fn answering_a_question_is_recorded_and_survives_a_release() {
4701        let mut t = task("asked something");
4702        t.block(vec!["q1".to_owned()], Some("which backend?".to_owned()));
4703        t.record_answer("Which backend?".to_owned(), "SQLite".to_owned());
4704        t.unblock("q1");
4705        assert_eq!(t.status, TaskStatus::Queued);
4706        assert_eq!(t.answers.len(), 1);
4707        assert_eq!(t.answers[0].answer, "SQLite");
4708
4709        // A release resets attempts, not evidence - the same rule
4710        // `releasing_a_held_task_gives_it_a_real_second_chance` asserts for
4711        // `runs`.
4712        t.release();
4713        assert_eq!(t.answers.len(), 1, "the answer is not lost on release");
4714    }
4715
4716    #[test]
4717    fn resumption_review_branch_requires_unchanged_authored_criteria() {
4718        for source in ["cli", "web"] {
4719            let mut t = task("review old candidate");
4720            t.request_review("candidate-A".into());
4721            t.hold_for_handover(Some("candidate-A".into()), "handover refused".into());
4722            let mut unchanged = t.clone();
4723            unchanged.release_operator(source, None);
4724            assert_eq!(unchanged.review_branch.as_deref(), Some("candidate-A"));
4725            t.edit(
4726                "review approved head".into(),
4727                "Reuse measured PR head B; fix Clippy; review".into(),
4728            )
4729            .unwrap();
4730            t.release_operator(source, None);
4731            assert!(t.review_branch.is_none());
4732            assert!(t.review_instruction.is_none());
4733            // Legacy records capture their old criteria at the supported edit.
4734            let mut legacy = unchanged;
4735            legacy.review_instruction = None;
4736            legacy.hold_for_handover(None, "still checked out".into());
4737            legacy
4738                .edit("new plan".into(), "Reuse measured PR head B".into())
4739                .unwrap();
4740            legacy.release_operator(source, None);
4741            assert!(legacy.review_branch.is_none());
4742        }
4743    }
4744
4745    #[test]
4746    fn a_refused_handover_keeps_the_review_branch_across_release() {
4747        let mut t = task("refused takeover");
4748        t.start("run-1".to_owned());
4749        t.hold_for_handover(Some("magi/eba2/A".to_owned()), "checked out".to_owned());
4750        assert_eq!(t.status, TaskStatus::Held);
4751        assert_eq!(t.attempts, 1);
4752        t.release();
4753        assert_eq!(t.status, TaskStatus::Queued);
4754        assert_eq!(t.attempts, 0);
4755        assert_eq!(t.review_branch.as_deref(), Some("magi/eba2/A"));
4756
4757        // A fresh competition chosen afterwards is not a review.
4758        t.hold_for_handover(None, "again".to_owned());
4759        t.requeue();
4760        assert!(t.review_branch.is_none());
4761
4762        // A manual hold never keeps one.
4763        let mut m = task("manual");
4764        m.review_branch = Some("magi/x/A".to_owned());
4765        m.hold_manual(None);
4766        m.release();
4767        assert!(m.review_branch.is_none());
4768    }
4769
4770    #[test]
4771    fn requesting_review_requeues_the_task_and_remembers_the_branch() {
4772        let mut t = task("blocked run with a surviving branch");
4773        t.start("run-1".to_owned());
4774        t.fail("blocked with major findings", 5);
4775        assert_eq!(t.status, TaskStatus::Failed);
4776
4777        t.request_review("magi/eba2/A".to_owned());
4778        assert_eq!(t.status, TaskStatus::Queued);
4779        assert_eq!(t.attempts, 0);
4780        assert_eq!(t.review_branch.as_deref(), Some("magi/eba2/A"));
4781
4782        // An ordinary release (a human overriding the choice) drops it again.
4783        t.release();
4784        assert!(t.review_branch.is_none());
4785    }
4786
4787    #[test]
4788    fn conductor_requeue_but_not_an_ordinary_release_forces_a_fresh_start() {
4789        let mut t = task("retry");
4790        t.start("run-1".to_owned());
4791        t.requeue();
4792        assert!(t.fresh_start);
4793
4794        t.release();
4795        assert!(!t.fresh_start);
4796    }
4797
4798    #[test]
4799    fn urgent_only_changes_queued_or_held_and_preserves_settings() {
4800        for status in [
4801            TaskStatus::Queued,
4802            TaskStatus::Held,
4803            TaskStatus::Running,
4804            TaskStatus::Done,
4805            TaskStatus::Failed,
4806            TaskStatus::Blocked,
4807            TaskStatus::Parked,
4808        ] {
4809            let mut t = task("urgent settings");
4810            t.status = status;
4811            t.attempts = 2;
4812            t.hold_reason = Some("waiting".into());
4813            t.priority = 7;
4814            t.interrupt = true;
4815            let before = serde_json::to_value(&t).unwrap();
4816            for urgent in [true, true, false, false] {
4817                let result = t.set_urgent(urgent);
4818                let mut expected = before.clone();
4819                if matches!(status, TaskStatus::Queued | TaskStatus::Held) {
4820                    result.unwrap();
4821                    expected["urgent"] = urgent.into();
4822                } else {
4823                    let error = result.unwrap_err().to_string();
4824                    assert!(error.contains(status.as_str()), "{error}");
4825                    assert!(error.contains("queued or held"), "{error}");
4826                }
4827                assert_eq!(serde_json::to_value(&t).unwrap(), expected);
4828            }
4829        }
4830    }
4831
4832    #[test]
4833    fn priority_can_be_changed_while_queued_but_not_while_running() {
4834        let mut t = task("reprioritise me");
4835        t.set_priority(5).unwrap();
4836        assert_eq!(t.priority, 5);
4837
4838        t.start("run-1".to_owned());
4839        let err = t.set_priority(9).unwrap_err().to_string();
4840        assert!(err.contains("running"), "{err}");
4841        assert_eq!(t.priority, 5, "the rejected write must not partially apply");
4842    }
4843
4844    #[test]
4845    fn interrupt_can_be_marked_while_queued_but_not_while_running() {
4846        let mut t = task("interrupt me");
4847        assert!(!t.interrupt, "off unless asked, same as any other task");
4848
4849        t.set_interrupt(true).unwrap();
4850        assert!(t.interrupt);
4851
4852        t.start("run-1".to_owned());
4853        assert!(
4854            !t.interrupt,
4855            "the mark is one-shot: dispatching the task fulfils it, \
4856             whatever the run that follows ends up doing"
4857        );
4858        let err = t.set_interrupt(true).unwrap_err().to_string();
4859        assert!(err.contains("running"), "{err}");
4860        // Clearing is always allowed, even on a running task - there is
4861        // nothing left for it to interrupt once it has been claimed.
4862        t.set_interrupt(false).unwrap();
4863        assert!(!t.interrupt);
4864    }
4865
4866    /// R2-1-1: a task whose run fails and requeues must not go on
4867    /// re-triggering `crate::daemon`'s interrupt scheduler on every later
4868    /// boundary, attempt after attempt, until it exhausts its budget.
4869    #[test]
4870    fn a_failed_run_does_not_leave_the_task_still_marked_to_interrupt() {
4871        let mut t = task("interrupt me");
4872        t.set_interrupt(true).unwrap();
4873        t.start("run-1".to_owned());
4874        t.fail("mock failure", 5);
4875        assert_eq!(t.status, TaskStatus::Failed);
4876        assert!(
4877            !t.interrupt,
4878            "one attempt already spent the mark; a retry is an ordinary \
4879             requeue, not a fresh interrupt request"
4880        );
4881    }
4882
4883    #[test]
4884    fn changing_priority_moves_a_task_ahead_in_the_real_queue_order() {
4885        let (_dir, q) = queue();
4886        let mut a = task("first filed");
4887        let mut b = task("second filed");
4888        a.id = "20260101-000001-aaaa".to_owned();
4889        b.id = "20260101-000002-bbbb".to_owned();
4890        q.put(&mut a).unwrap();
4891        q.put(&mut b).unwrap();
4892
4893        assert_eq!(
4894            q.next_runnable().unwrap().id,
4895            a.id,
4896            "with equal priority the older task goes first, so a burst of \
4897             new work cannot starve it"
4898        );
4899        assert_eq!(
4900            q.list()[0].id,
4901            b.id,
4902            "but the list an operator reads is newest first, the same as \
4903             before priority existed - a's turn to run does not make it the \
4904             newest task"
4905        );
4906
4907        let mut a = q.get(&a.id).unwrap();
4908        a.set_priority(10).unwrap();
4909        q.put(&mut a).unwrap();
4910
4911        assert_eq!(
4912            q.next_runnable().unwrap().id,
4913            a.id,
4914            "a raised priority must be reflected the moment it is saved"
4915        );
4916        // `magi task list` and `GET /api/queue` both print `Queue::list()`
4917        // directly, so the raised task has to lead there too - not only in
4918        // what the loop would claim next.
4919        assert_eq!(
4920            q.list()[0].id,
4921            a.id,
4922            "the raised task must sort first in the list an operator reads, \
4923             not only in next_runnable's own ordering"
4924        );
4925    }
4926
4927    #[test]
4928    fn editing_replaces_title_and_instruction_but_keeps_identity_and_history() {
4929        let mut t = Task::new(
4930            "old title".to_owned(),
4931            "old instruction".to_owned(),
4932            PathBuf::from("/repo"),
4933            Source::Agent {
4934                run: "20260101-000000-beef".to_owned(),
4935                node: "implement".to_owned(),
4936            },
4937        );
4938        let id = t.id.clone();
4939        let created_at = t.created_at;
4940        t.runs.push("20260101-000000-beef".to_owned());
4941
4942        t.edit("new title".to_owned(), "new instruction".to_owned())
4943            .unwrap();
4944
4945        assert_eq!(t.title, "new title");
4946        assert_eq!(t.instruction, "new instruction");
4947        assert_eq!(t.id, id, "editing must not mint a new id");
4948        assert_eq!(t.created_at, created_at);
4949        assert_eq!(
4950            t.source,
4951            Source::Agent {
4952                run: "20260101-000000-beef".to_owned(),
4953                node: "implement".to_owned(),
4954            },
4955            "editing must not turn agent attribution into human"
4956        );
4957        assert_eq!(t.runs, ["20260101-000000-beef"]);
4958    }
4959
4960    #[test]
4961    fn editing_is_refused_once_a_task_is_running_or_finished() {
4962        let mut running = task("in flight");
4963        running.start("run-1".to_owned());
4964        let err = running
4965            .edit("x".to_owned(), "y".to_owned())
4966            .unwrap_err()
4967            .to_string();
4968        assert!(err.contains("running"), "{err}");
4969
4970        let mut done = task("finished");
4971        done.succeed();
4972        let err = done
4973            .edit("x".to_owned(), "y".to_owned())
4974            .unwrap_err()
4975            .to_string();
4976        assert!(err.contains("done"), "{err}");
4977
4978        // Both queued and held are the point of the feature and must work.
4979        let mut queued = task("waiting");
4980        queued.edit("x".to_owned(), "y".to_owned()).unwrap();
4981        let mut held = task("parked");
4982        held.hold_machine(None);
4983        held.edit("x".to_owned(), "y".to_owned()).unwrap();
4984    }
4985
4986    #[test]
4987    fn a_task_recorded_without_a_hold_reason_still_reads_as_none() {
4988        let (_dir, q) = queue();
4989        let path = q.path_of("20260101-000000-aaaa");
4990        std::fs::create_dir_all(q.root()).unwrap();
4991        std::fs::write(
4992            &path,
4993            serde_json::json!({
4994                "schema": SCHEMA,
4995                "id": "20260101-000000-aaaa",
4996                "title": "from before hold reasons existed",
4997                "instruction": "from before hold reasons existed",
4998                "repo": ".",
4999                "source": { "kind": "human" },
5000                "status": "held",
5001                "created_at": Timestamp::now().to_string(),
5002                "updated_at": Timestamp::now().to_string(),
5003            })
5004            .to_string(),
5005        )
5006        .unwrap();
5007
5008        let task = q.get("20260101-000000-aaaa").expect("must still read");
5009        assert!(task.hold_reason.is_none());
5010        assert!(task.operator_held());
5011    }
5012
5013    #[test]
5014    fn a_legacy_reasoned_hold_defaults_to_operator_protection() {
5015        let (_dir, q) = queue();
5016        let path = q.path_of("20260101-000000-bbbb");
5017        std::fs::create_dir_all(q.root()).unwrap();
5018        std::fs::write(
5019            &path,
5020            serde_json::json!({
5021                "schema": 2,
5022                "id": "20260101-000000-bbbb",
5023                "title": "old manual recovery",
5024                "instruction": "old manual recovery",
5025                "repo": ".",
5026                "source": { "kind": "human" },
5027                "status": "held",
5028                "hold_reason": "active manual recovery run20260912-224242-daf5",
5029                "created_at": Timestamp::now().to_string(),
5030                "updated_at": Timestamp::now().to_string(),
5031            })
5032            .to_string(),
5033        )
5034        .unwrap();
5035
5036        let task = q.get("20260101-000000-bbbb").expect("must still read");
5037        assert_eq!(task.hold_source, None);
5038        assert!(task.operator_held());
5039    }
5040
5041    #[test]
5042    fn a_task_recorded_without_a_diagnostic_still_reads_as_none() {
5043        let (_dir, q) = queue();
5044        let path = q.path_of("20260101-000000-aaaa");
5045        std::fs::create_dir_all(q.root()).unwrap();
5046        std::fs::write(
5047            &path,
5048            serde_json::json!({
5049                "schema": SCHEMA,
5050                "id": "20260101-000000-aaaa",
5051                "title": "from before diagnostics existed",
5052                "instruction": "from before diagnostics existed",
5053                "repo": ".",
5054                "source": { "kind": "human" },
5055                "status": "held",
5056                "created_at": Timestamp::now().to_string(),
5057                "updated_at": Timestamp::now().to_string(),
5058            })
5059            .to_string(),
5060        )
5061        .unwrap();
5062
5063        let task = q.get("20260101-000000-aaaa").expect("must still read");
5064        assert!(task.diagnostic.is_none());
5065    }
5066
5067    #[test]
5068    fn a_schema_1_task_with_no_blocking_fields_still_reads() {
5069        // Written by a build that predates `blocked_by`, `block_reason`,
5070        // `answers` and `review_branch` entirely - literal `"schema": 1`,
5071        // not `SCHEMA`, since the whole point is a build older than this one.
5072        let (_dir, q) = queue();
5073        let path = q.path_of("20260101-000000-aaaa");
5074        std::fs::create_dir_all(q.root()).unwrap();
5075        std::fs::write(
5076            &path,
5077            serde_json::json!({
5078                "schema": 1,
5079                "id": "20260101-000000-aaaa",
5080                "title": "from before blocking existed",
5081                "instruction": "from before blocking existed",
5082                "repo": ".",
5083                "source": { "kind": "human" },
5084                "status": "queued",
5085                "created_at": Timestamp::now().to_string(),
5086                "updated_at": Timestamp::now().to_string(),
5087            })
5088            .to_string(),
5089        )
5090        .unwrap();
5091
5092        let task = q.get("20260101-000000-aaaa").expect("must still read");
5093        assert!(task.blocked_by.is_empty());
5094        assert!(task.block_reason.is_none());
5095        assert!(task.answers.is_empty());
5096        assert!(task.review_branch.is_none());
5097    }
5098
5099    #[test]
5100    fn releasing_or_finishing_a_task_clears_its_stale_diagnostic() {
5101        // A diagnostic belongs to the run that produced it. Left in place
5102        // across a release, an unrelated later failure - a config error, say -
5103        // would go on showing evidence for a problem that is no longer why the
5104        // task is stuck.
5105        let mut held = task("diagnosed");
5106        held.start("run-1".to_owned());
5107        held.fail("gate red", 1);
5108        held.diagnostic = Some("cargo test failed: ...".to_owned());
5109        assert_eq!(held.status, TaskStatus::Held);
5110
5111        held.release();
5112        assert!(held.diagnostic.is_none());
5113
5114        held.diagnostic = Some("cargo test failed: ...".to_owned());
5115        held.succeed();
5116        assert!(held.diagnostic.is_none());
5117    }
5118
5119    #[test]
5120    fn failing_a_task_always_clears_whatever_diagnostic_it_carried() {
5121        let mut t = task("retried");
5122        t.start("run-1".to_owned());
5123        t.diagnostic = Some("stale evidence from a previous hold".to_owned());
5124        t.fail("unrelated config error", 5);
5125        assert_eq!(t.status, TaskStatus::Failed);
5126        assert!(
5127            t.diagnostic.is_none(),
5128            "fail() must not let an old diagnostic outlive the run that produced it"
5129        );
5130    }
5131
5132    #[test]
5133    fn a_claim_is_exclusive_and_releases_on_drop() {
5134        let (_dir, q) = queue();
5135        let mut t = task("contended");
5136        q.put(&mut t).unwrap();
5137
5138        let held = q.claim(&t.id).unwrap();
5139        assert!(
5140            q.claim(&t.id).is_err(),
5141            "two daemons must not drive one task into two runs"
5142        );
5143        drop(held);
5144        assert!(q.claim(&t.id).is_ok(), "a released claim is reclaimable");
5145    }
5146
5147    #[test]
5148    fn a_round_trip_survives_disk() {
5149        let (_dir, q) = queue();
5150        let mut t = Task::new(
5151            "titled".to_owned(),
5152            "body".to_owned(),
5153            PathBuf::from("/repo"),
5154            Source::Agent {
5155                run: "20260101-000000-beef".to_owned(),
5156                node: "implement".to_owned(),
5157            },
5158        );
5159        t.priority = 3;
5160        q.put(&mut t).unwrap();
5161
5162        let back = q.get(&t.id).unwrap();
5163        assert_eq!(back.id, t.id);
5164        assert_eq!(back.priority, 3);
5165        assert_eq!(back.source.label(), "implement@beef");
5166        // A prefix is enough, the way run ids work everywhere else.
5167        assert_eq!(q.get(t.short()).unwrap().id, t.id);
5168    }
5169
5170    #[test]
5171    fn an_unreadable_task_does_not_take_the_queue_down() {
5172        let (_dir, q) = queue();
5173        let mut t = task("fine");
5174        q.put(&mut t).unwrap();
5175        std::fs::write(q.root().join("broken.json"), "{ not json").unwrap();
5176
5177        let listed = q.list();
5178        assert_eq!(listed.len(), 1, "the readable task still lists");
5179        assert_eq!(listed[0].id, t.id);
5180    }
5181
5182    #[test]
5183    fn a_task_recorded_without_a_solo_field_still_reads_as_not_solo() {
5184        let (_dir, q) = queue();
5185        let path = q.path_of("20260101-000000-aaaa");
5186        std::fs::create_dir_all(q.root()).unwrap();
5187        std::fs::write(
5188            &path,
5189            serde_json::json!({
5190                "schema": SCHEMA,
5191                "id": "20260101-000000-aaaa",
5192                "title": "from before solo existed",
5193                "instruction": "from before solo existed",
5194                "repo": ".",
5195                "source": { "kind": "human" },
5196                "status": "queued",
5197                "created_at": Timestamp::now().to_string(),
5198                "updated_at": Timestamp::now().to_string(),
5199            })
5200            .to_string(),
5201        )
5202        .unwrap();
5203
5204        let task = q.get("20260101-000000-aaaa").expect("must still read");
5205        assert!(!task.solo, "a queue file with no `solo` field means false");
5206    }
5207
5208    #[test]
5209    fn a_task_recorded_without_an_urgent_field_still_reads_as_not_urgent() {
5210        let (_dir, q) = queue();
5211        let path = q.path_of("20260101-000000-bbbb");
5212        std::fs::create_dir_all(q.root()).unwrap();
5213        std::fs::write(
5214            &path,
5215            serde_json::json!({
5216                "schema": SCHEMA,
5217                "id": "20260101-000000-bbbb",
5218                "title": "from before urgent existed",
5219                "instruction": "from before urgent existed",
5220                "repo": ".",
5221                "source": { "kind": "human" },
5222                "status": "queued",
5223                "created_at": Timestamp::now().to_string(),
5224                "updated_at": Timestamp::now().to_string(),
5225            })
5226            .to_string(),
5227        )
5228        .unwrap();
5229
5230        let task = q.get("20260101-000000-bbbb").expect("must still read");
5231        assert!(
5232            !task.urgent,
5233            "a queue file with no `urgent` field means false, same as `solo`"
5234        );
5235    }
5236
5237    #[test]
5238    fn a_task_from_a_future_schema_is_refused_rather_than_guessed_at() {
5239        let (_dir, q) = queue();
5240        let mut t = task("from the future");
5241        q.put(&mut t).unwrap();
5242        let path = q.path_of(&t.id);
5243        let body = std::fs::read_to_string(&path)
5244            .unwrap()
5245            .replace(&format!("\"schema\": {SCHEMA}"), "\"schema\": 99");
5246        std::fs::write(&path, body).unwrap();
5247
5248        let err = q.get(&t.id).unwrap_err().to_string();
5249        assert!(err.contains("schema 99"), "{err}");
5250    }
5251
5252    #[test]
5253    fn revision_moves_when_the_queue_changes() {
5254        let (_dir, q) = queue();
5255        assert_eq!(q.revision(), 0, "an empty queue has no revision");
5256        let mut t = task("first");
5257        q.put(&mut t).unwrap();
5258        assert!(q.revision() > 0, "a written task moves the revision");
5259    }
5260
5261    #[test]
5262    fn revision_moves_when_deleting_an_older_task() {
5263        let (dir, q) = queue();
5264        let questions = Questions::at(dir.path().join("questions"));
5265        let mut t1 = task("older");
5266        q.put(&mut t1).unwrap();
5267        // Ensure mtime ticks forward.
5268        std::thread::sleep(std::time::Duration::from_millis(10));
5269        let mut t2 = task("newer");
5270        q.put(&mut t2).unwrap();
5271
5272        let rev_before = q.revision();
5273        q.remove(&t1.id, false, &questions).unwrap();
5274        let rev_after = q.revision();
5275
5276        assert_ne!(
5277            rev_before, rev_after,
5278            "deleting an older task must change the revision so other clients see the deletion"
5279        );
5280    }
5281
5282    #[test]
5283    fn removing_a_task_takes_it_out_of_the_listing() {
5284        let (dir, q) = queue();
5285        let questions = Questions::at(dir.path().join("questions"));
5286        let mut t = task("delete me");
5287        q.put(&mut t).unwrap();
5288        let removed = q.remove(t.short(), false, &questions).unwrap();
5289        assert_eq!(removed.id, t.id, "a prefix resolves before deleting");
5290        assert!(removed.released.is_empty() && removed.still_blocked.is_empty());
5291        assert!(q.list().is_empty());
5292        assert!(
5293            q.remove(&t.id, false, &questions).is_err(),
5294            "removing twice is an error"
5295        );
5296    }
5297
5298    #[test]
5299    fn removing_a_task_takes_its_stale_lock_with_it() {
5300        let (dir, q) = queue();
5301        let questions = Questions::at(dir.path().join("questions"));
5302        let mut t = task("interrupted");
5303        q.put(&mut t).unwrap();
5304
5305        // A daemon killed mid-run leaves this behind. Nothing holds it: the
5306        // process that would have dropped the guard is gone.
5307        let claim = q.claim(&t.id).unwrap();
5308        std::mem::forget(claim);
5309        assert!(
5310            q.claim(&t.id).is_err(),
5311            "the orphaned lock is what makes the task look claimed"
5312        );
5313
5314        // A live daemon on this task is refused, whatever the lock says.
5315        let err = q.remove(&t.id, true, &questions).unwrap_err().to_string();
5316        assert!(err.contains("live daemon"), "{err}");
5317        assert!(q.get(&t.id).is_ok(), "a refused delete keeps the task");
5318
5319        // With no daemon behind it, the lock is stale and goes with the task.
5320        q.remove(&t.id, false, &questions).unwrap();
5321        assert!(q.list().is_empty());
5322        let mut again = task("interrupted");
5323        again.id = t.id.clone();
5324        q.put(&mut again).unwrap();
5325        assert!(
5326            q.claim(&t.id).is_ok(),
5327            "a task that comes back must be claimable, which a left-behind lock would prevent"
5328        );
5329    }
5330
5331    fn notices_of(dir: &Path) -> Vec<crate::notices::Notice> {
5332        crate::notices::Notices::at(dir.join("notifications")).list()
5333    }
5334
5335    #[test]
5336    fn removing_a_sole_dependency_releases_the_dependent_without_a_hold() {
5337        let (dir, q) = queue();
5338        let questions = Questions::at(dir.path().join("questions"));
5339        let mut dep = task("dependency");
5340        q.put(&mut dep).unwrap();
5341        let mut blocked = task("waiting");
5342        blocked.block(vec![dep.id.clone()], Some("waits".to_owned()));
5343        q.put(&mut blocked).unwrap();
5344
5345        let removed = q.remove(&dep.id, false, &questions).unwrap();
5346        assert_eq!(removed.released, [blocked.id.clone()]);
5347        assert!(removed.still_blocked.is_empty());
5348
5349        let after = q.get(&blocked.id).unwrap();
5350        assert_eq!(after.status, TaskStatus::Queued);
5351        assert!(after.blocked_by.is_empty());
5352        assert!(after.block_reason.is_none());
5353        let notes = notices_of(dir.path());
5354        assert_eq!(notes.len(), 1, "{notes:?}");
5355        assert_eq!(notes[0].severity, crate::notices::Severity::Info);
5356        assert_eq!(
5357            notes[0].link,
5358            Some(crate::notices::Link::Task {
5359                id: blocked.id.clone(),
5360            })
5361        );
5362    }
5363
5364    #[test]
5365    fn removing_one_of_two_dependencies_keeps_the_other() {
5366        let (dir, q) = queue();
5367        let questions = Questions::at(dir.path().join("questions"));
5368        let mut dep = task("dependency");
5369        q.put(&mut dep).unwrap();
5370        let mut other = task("other");
5371        q.put(&mut other).unwrap();
5372        let mut blocked = task("waiting");
5373        blocked.block(
5374            vec![dep.id.clone(), other.id.clone()],
5375            Some("waits on both".to_owned()),
5376        );
5377        q.put(&mut blocked).unwrap();
5378
5379        let removed = q.remove(&dep.id, false, &questions).unwrap();
5380        assert!(removed.released.is_empty());
5381        assert_eq!(removed.still_blocked, [blocked.id.clone()]);
5382
5383        let after = q.get(&blocked.id).unwrap();
5384        assert_eq!(after.status, TaskStatus::Blocked);
5385        assert_eq!(after.blocked_by, [other.id.clone()]);
5386        // The tombstone stays while a task still names the id... only this
5387        // one's dependency is gone, so nothing references it and it may go.
5388        assert!(missing_blockers(&q, &questions, &after.blocked_by).is_empty());
5389    }
5390
5391    #[test]
5392    fn a_dependency_deleted_before_its_dependents_were_rewritten_is_released_later() {
5393        let (dir, q) = queue();
5394        let questions = Questions::at(dir.path().join("questions"));
5395        let mut dep = task("dependency");
5396        q.put(&mut dep).unwrap();
5397        let mut blocked = task("waiting");
5398        blocked.block(vec![dep.id.clone()], None);
5399        q.put(&mut blocked).unwrap();
5400
5401        // The dependent is claimed elsewhere, so `remove` has to skip it.
5402        let claim = q.claim(&blocked.id).unwrap();
5403        let removed = q.remove(&dep.id, false, &questions).unwrap();
5404        assert!(removed.released.is_empty());
5405        drop(claim);
5406
5407        let mut task = q.get(&blocked.id).unwrap();
5408        assert_eq!(task.status, TaskStatus::Blocked);
5409        assert!(missing_blockers(&q, &questions, &task.blocked_by).is_empty());
5410        assert_eq!(
5411            q.apply_deleted_blockers(&mut task, &questions),
5412            [dep.id.clone()]
5413        );
5414        assert_eq!(task.status, TaskStatus::Queued);
5415    }
5416
5417    #[test]
5418    fn dependency_resolution_short_deleted_reference_releases_only_its_waiters() {
5419        let (dir, q) = queue();
5420        let questions = Questions::at(dir.path().join("questions"));
5421        let mut dep = task("dependency");
5422        dep.id = "20261013-193611-ca5b".into();
5423        q.put(&mut dep).unwrap();
5424        let mut waiting = task("waiting");
5425        waiting.block(vec!["ca5b".into()], None);
5426        q.put(&mut waiting).unwrap();
5427        q.remove(&dep.id, false, &questions).unwrap();
5428        assert_eq!(q.get(&waiting.id).unwrap().status, TaskStatus::Queued);
5429        assert_eq!(
5430            dependency(&q, &questions, "ca5b"),
5431            Dependency::Deleted(dep.id)
5432        );
5433    }
5434
5435    #[test]
5436    fn dependency_resolution_preserves_cross_store_ambiguity_and_exact_ids() {
5437        let (dir, queue) = queue();
5438        let questions = Questions::at(dir.path().join("questions"));
5439        let mut dep = task("dependency");
5440        dep.id = "20261013-193611-ca5b".into();
5441        queue.put(&mut dep).unwrap();
5442        std::fs::create_dir_all(questions.root()).unwrap();
5443        let question_id = "20261014-193611-ca5b";
5444        std::fs::write(questions.path_of(question_id), "unreadable question").unwrap();
5445        assert_eq!(questions.resolve_id("ca5b").unwrap(), question_id);
5446        assert_eq!(
5447            dependency(&queue, &questions, "ca5b"),
5448            Dependency::Ambiguous
5449        );
5450        assert_eq!(
5451            dependency(&queue, &questions, &dep.id),
5452            Dependency::Task(dep.id)
5453        );
5454        assert_eq!(
5455            dependency(&queue, &questions, question_id),
5456            Dependency::Question(question_id.into())
5457        );
5458        assert_eq!(
5459            dependency(&queue, &questions, "missing"),
5460            Dependency::Missing
5461        );
5462    }
5463
5464    #[test]
5465    fn dependency_resolution_directory_errors_are_unknown_not_missing() {
5466        let dir = tempfile::tempdir().unwrap();
5467        let q = Queue::at(dir.path().join("not-a-directory"));
5468        std::fs::write(q.root(), "file").unwrap();
5469        let questions = Questions::at(dir.path().join("questions"));
5470        assert_eq!(dependency(&q, &questions, "ca5b"), Dependency::Unknown);
5471        assert!(missing_blockers(&q, &questions, &["ca5b".into()]).is_empty());
5472    }
5473
5474    #[test]
5475    fn a_dependency_without_a_tombstone_is_still_missing() {
5476        let (dir, q) = queue();
5477        let questions = Questions::at(dir.path().join("questions"));
5478        let mut dep = task("dependency");
5479        q.put(&mut dep).unwrap();
5480        std::fs::remove_file(q.path_of(&dep.id)).unwrap();
5481        assert_eq!(
5482            missing_blockers(&q, &questions, std::slice::from_ref(&dep.id)),
5483            [dep.id.clone()]
5484        );
5485        assert!(deleted_blockers(&q, &questions, std::slice::from_ref(&dep.id)).is_empty());
5486    }
5487
5488    #[test]
5489    fn a_held_dependent_is_left_alone_by_a_dependency_deletion() {
5490        let mut t = task("held");
5491        t.hold_machine(Some("because".to_owned()));
5492        t.blocked_by = vec!["gone".to_owned()];
5493        assert!(!t.dependency_deleted("gone"));
5494        assert_eq!(t.status, TaskStatus::Held);
5495    }
5496
5497    #[test]
5498    fn a_failed_record_removal_takes_the_tombstone_back() {
5499        let (_dir, q) = queue();
5500        let mut t = task("stays");
5501        q.put(&mut t).unwrap();
5502        q.write_tombstone(&t.id).unwrap();
5503        let err = q.remove_record_with_attachments(&t.id, |_| Err(std::io::Error::other("nope")));
5504        assert!(err.is_err());
5505        // `remove` is what withdraws the marker; a live record is never
5506        // treated as deleted whatever is on disk.
5507        assert!(!q.was_deleted(&t.id));
5508    }
5509
5510    fn source_file(dir: &Path, name: &str, body: &str) -> PathBuf {
5511        let p = dir.join(name);
5512        std::fs::write(&p, body).unwrap();
5513        p
5514    }
5515
5516    #[test]
5517    fn an_attachment_copy_survives_deleting_its_source() {
5518        let (dir, q) = queue();
5519        let src = source_file(dir.path(), "shot.png", "pixels");
5520        let mut t = task("with a picture");
5521        let names = q.attach(&mut t, std::slice::from_ref(&src)).unwrap();
5522        q.put(&mut t).unwrap();
5523        std::fs::remove_file(&src).unwrap();
5524        assert_eq!(names, ["shot.png"]);
5525        let loaded = q.get(&t.id).unwrap();
5526        let paths = q.attachment_paths(&loaded);
5527        assert_eq!(paths.len(), 1);
5528        assert_eq!(std::fs::read_to_string(&paths[0]).unwrap(), "pixels");
5529    }
5530
5531    #[test]
5532    fn attachment_names_that_could_traverse_or_are_odd_are_refused() {
5533        let (dir, q) = queue();
5534        let mut t = task("bad names");
5535        for name in ["a..b.png", ".hidden", "with space.png", "-x.png"] {
5536            let src = source_file(dir.path(), name, "x");
5537            assert!(
5538                q.attach(&mut t, &[src]).is_err(),
5539                "`{name}` must be refused"
5540            );
5541        }
5542        // A drive-qualified name cannot exist as a file on Windows (joining it
5543        // to a directory yields a drive-relative path to `foo.png` instead),
5544        // so the rule is asserted on the name itself, everywhere.
5545        assert!(!crate::ask::valid_asset_name("C:foo.png"));
5546        #[cfg(not(windows))]
5547        {
5548            let src = source_file(dir.path(), "C:foo.png", "x");
5549            assert!(q.attach(&mut t, &[src]).is_err());
5550        }
5551        let long = format!("{}.png", "a".repeat(70));
5552        let src = source_file(dir.path(), &long, "x");
5553        assert!(q.attach(&mut t, &[src]).is_err());
5554        assert!(t.attachments.is_empty());
5555        assert!(!q.attachments_dir(&t.id).exists());
5556    }
5557
5558    #[test]
5559    fn a_taken_attachment_name_is_numbered_not_overwritten() {
5560        let (dir, q) = queue();
5561        let a = source_file(dir.path(), "shot.png", "one");
5562        let sub = dir.path().join("other");
5563        std::fs::create_dir_all(&sub).unwrap();
5564        let b = source_file(&sub, "shot.png", "two");
5565        let mut t = task("collision");
5566        q.attach(&mut t, &[a]).unwrap();
5567        q.attach(&mut t, &[b]).unwrap();
5568        assert_eq!(t.attachments, ["shot.png", "shot-2.png"]);
5569        let paths = q.attachment_paths(&t);
5570        assert_eq!(std::fs::read_to_string(&paths[0]).unwrap(), "one");
5571        assert_eq!(std::fs::read_to_string(&paths[1]).unwrap(), "two");
5572    }
5573
5574    #[test]
5575    fn a_renumbered_name_stays_inside_the_length_bound() {
5576        let (dir, q) = queue();
5577        let name = format!("{}.png", "a".repeat(60));
5578        assert_eq!(name.len(), 64);
5579        let a = source_file(dir.path(), &name, "one");
5580        let sub = dir.path().join("other");
5581        std::fs::create_dir_all(&sub).unwrap();
5582        let b = source_file(&sub, &name, "two");
5583        let mut t = task("long");
5584        q.attach(&mut t, &[a, b]).unwrap();
5585        assert_eq!(t.attachments.len(), 2);
5586        assert!(
5587            t.attachments
5588                .iter()
5589                .all(|n| crate::ask::valid_asset_name(n))
5590        );
5591        assert!(t.attachments[1].ends_with("-2.png"));
5592    }
5593
5594    #[test]
5595    fn a_failed_attach_keeps_existing_attachments_and_leaves_no_partial_copy() {
5596        let (dir, q) = queue();
5597        let good = source_file(dir.path(), "good.png", "ok");
5598        let mut t = task("partial");
5599        q.attach(&mut t, &[good]).unwrap();
5600        let more = source_file(dir.path(), "more.png", "ok");
5601        let missing = dir.path().join("missing.png");
5602        assert!(q.attach(&mut t, &[more, missing]).is_err());
5603        assert_eq!(t.attachments, ["good.png"]);
5604        let on_disk: Vec<_> = std::fs::read_dir(q.attachments_dir(&t.id))
5605            .unwrap()
5606            .flatten()
5607            .collect();
5608        assert_eq!(on_disk.len(), 1);
5609    }
5610
5611    /// Make the next `put` of `t` fail: its temp file's path is a directory.
5612    fn block_put(q: &Queue, t: &Task) -> PathBuf {
5613        let tmp = q.path_of(&t.id).with_extension("json.tmp");
5614        std::fs::create_dir_all(&tmp).unwrap();
5615        tmp
5616    }
5617
5618    #[test]
5619    fn a_failed_put_leaves_no_new_attachment_directory() {
5620        let (dir, q) = queue();
5621        let mut t = task("fresh");
5622        let tmp = block_put(&q, &t);
5623        let src = source_file(dir.path(), "shot.png", "x");
5624        assert!(q.attach_and_put(&mut t, &[src]).is_err());
5625        assert!(t.attachments.is_empty());
5626        assert!(!q.attachments_dir(&t.id).exists());
5627        assert!(!q.path_of(&t.id).exists());
5628        std::fs::remove_dir(tmp).unwrap();
5629    }
5630
5631    #[test]
5632    fn a_failed_put_removes_only_the_copy_it_just_made() {
5633        let (dir, q) = queue();
5634        let mut t = task("edited");
5635        let first = source_file(dir.path(), "first.png", "1");
5636        q.attach_and_put(&mut t, &[first]).unwrap();
5637        block_put(&q, &t);
5638        let second = source_file(dir.path(), "second.png", "2");
5639        assert!(q.attach_and_put(&mut t, &[second]).is_err());
5640        assert_eq!(t.attachments, ["first.png"]);
5641        let on_disk: Vec<_> = std::fs::read_dir(q.attachments_dir(&t.id))
5642            .unwrap()
5643            .flatten()
5644            .map(|e| e.file_name().to_string_lossy().into_owned())
5645            .collect();
5646        assert_eq!(on_disk, ["first.png"]);
5647        assert_eq!(q.get(&t.id).unwrap().attachments, ["first.png"]);
5648    }
5649
5650    #[test]
5651    fn a_leftover_removing_directory_is_swept_by_the_next_removal() {
5652        let (dir, q) = queue();
5653        let questions = Questions::at(dir.path().join("questions"));
5654        let gone = task("gone");
5655        let mut other = task("other");
5656        let mut live = task("live");
5657        q.put(&mut other).unwrap();
5658        q.put(&mut live).unwrap();
5659        // `gone` has no record: its removal finished deleting the record but
5660        // not the set-aside attachments.
5661        let orphan = q.root.join(format!("{}.attachments.removing", gone.id));
5662        std::fs::create_dir_all(&orphan).unwrap();
5663        std::fs::write(orphan.join("shot.png"), "x").unwrap();
5664        // `live` still has a record, so its `.removing` belongs to a removal
5665        // in progress and must be left alone.
5666        let busy = q.root.join(format!("{}.attachments.removing", live.id));
5667        std::fs::create_dir_all(&busy).unwrap();
5668
5669        q.remove(&other.id, false, &questions).unwrap();
5670        assert!(!orphan.exists(), "an orphan is swept");
5671        assert!(busy.exists(), "a removal in progress is left alone");
5672    }
5673
5674    #[test]
5675    fn a_blocked_aside_rename_fails_the_removal_and_loses_nothing() {
5676        let (dir, q) = queue();
5677        let questions = Questions::at(dir.path().join("questions"));
5678        let mut t = task("stuck");
5679        let src = source_file(dir.path(), "shot.png", "x");
5680        q.attach_and_put(&mut t, &[src]).unwrap();
5681        // A non-empty directory already at the set-aside name makes the rename
5682        // fail; its record is present, so the sweep leaves it in place.
5683        let aside = q.root.join(format!("{}.attachments.removing", t.id));
5684        std::fs::create_dir_all(&aside).unwrap();
5685        std::fs::write(aside.join("old.png"), "o").unwrap();
5686        assert!(q.remove(&t.id, false, &questions).is_err());
5687        assert!(q.path_of(&t.id).exists());
5688        assert!(q.attachments_dir(&t.id).join("shot.png").is_file());
5689    }
5690
5691    #[test]
5692    fn a_failed_record_removal_puts_the_attachments_back() {
5693        let (dir, q) = queue();
5694        let mut t = task("rollback");
5695        let src = source_file(dir.path(), "shot.png", "x");
5696        q.attach_and_put(&mut t, &[src]).unwrap();
5697        let err = q
5698            .remove_record_with_attachments(&t.id, |_| {
5699                Err(std::io::Error::other("injected failure"))
5700            })
5701            .unwrap_err();
5702        assert!(format!("{err:#}").contains("injected failure"));
5703        assert!(q.path_of(&t.id).exists());
5704        assert!(q.attachments_dir(&t.id).join("shot.png").is_file());
5705        assert!(
5706            !q.root
5707                .join(format!("{}.attachments.removing", t.id))
5708                .exists()
5709        );
5710    }
5711
5712    #[test]
5713    fn editing_a_task_keeps_its_attachments() {
5714        let (dir, q) = queue();
5715        let src = source_file(dir.path(), "shot.png", "x");
5716        let mut t = task("editable");
5717        q.attach(&mut t, &[src]).unwrap();
5718        t.edit("new".to_owned(), "new text".to_owned()).unwrap();
5719        q.put(&mut t).unwrap();
5720        assert_eq!(q.get(&t.id).unwrap().attachments, ["shot.png"]);
5721    }
5722
5723    #[test]
5724    fn removing_a_task_deletes_its_attachments() {
5725        let (dir, q) = queue();
5726        let questions = Questions::at(dir.path().join("questions"));
5727        let src = source_file(dir.path(), "shot.png", "x");
5728        let mut t = task("doomed");
5729        q.attach(&mut t, &[src]).unwrap();
5730        q.put(&mut t).unwrap();
5731        assert!(q.attachments_dir(&t.id).is_dir());
5732        q.remove(&t.id, false, &questions).unwrap();
5733        assert!(!q.attachments_dir(&t.id).exists());
5734        assert!(q.list().is_empty());
5735    }
5736
5737    #[test]
5738    fn a_task_written_before_attachments_still_reads() {
5739        let (_dir, q) = queue();
5740        let mut t = task("old");
5741        q.put(&mut t).unwrap();
5742        let path = q.path_of(&t.id);
5743        let mut v: serde_json::Value =
5744            serde_json::from_str(&std::fs::read_to_string(&path).unwrap()).unwrap();
5745        v.as_object_mut().unwrap().remove("attachments");
5746        std::fs::write(&path, v.to_string()).unwrap();
5747        assert!(q.get(&t.id).unwrap().attachments.is_empty());
5748    }
5749
5750    #[test]
5751    fn attachment_paths_are_absolute_even_when_the_root_is_relative() {
5752        let q = Queue::at(PathBuf::from("relative-queue"));
5753        let mut t = task("rel");
5754        t.attachments.push("shot.png".to_owned());
5755        let paths = q.attachment_paths(&t);
5756        assert!(paths[0].is_absolute(), "{}", paths[0].display());
5757        assert!(paths[0].ends_with(format!("{}.attachments/shot.png", t.id)));
5758    }
5759
5760    fn upgrade_parked(id: &str, started: &str) -> Task {
5761        let mut t = task(id);
5762        t.id = id.into();
5763        t.start(format!("run-{id}"));
5764        t.park("upgrade");
5765        t.record_pass_at(
5766            &format!("run-{id}"),
5767            0,
5768            Some(started.parse().unwrap()),
5769            1,
5770            Some(crate::run::ParkCause::Upgrade {
5771                from: "old".into(),
5772                to: None,
5773            }),
5774        );
5775        t
5776    }
5777
5778    #[test]
5779    fn upgrade_resume_order_follows_dispatch_claim_not_graph_start() {
5780        // A was claimed first but its graph pass started later (slow start-up).
5781        let stamp = |id: &str, dispatched: &str, started: &str| {
5782            let mut t = task(id);
5783            t.id = id.into();
5784            t.start(format!("run-{id}"));
5785            t.park("upgrade");
5786            t.dispatched_at = Some(dispatched.parse().unwrap());
5787            t.record_pass_at(
5788                &format!("run-{id}"),
5789                0,
5790                Some(started.parse().unwrap()),
5791                1,
5792                Some(crate::run::ParkCause::Upgrade {
5793                    from: "old".into(),
5794                    to: None,
5795                }),
5796            );
5797            t
5798        };
5799        let a = stamp("a", "2026-10-22T00:00:01Z", "2026-10-22T00:00:09Z");
5800        let b = stamp("b", "2026-10-22T00:00:02Z", "2026-10-22T00:00:03Z");
5801        assert!(dispatch_order(&a, &b).is_lt());
5802    }
5803
5804    #[test]
5805    fn upgrade_resume_order_survives_queue_reload_and_reversed_settlement() {
5806        let (_dir, q) = queue();
5807        let mut later = upgrade_parked("later", "2026-10-22T00:00:02Z");
5808        let mut earlier = upgrade_parked("earlier", "2026-10-22T00:00:01Z");
5809        earlier.priority = -10;
5810        let mut fresh = task("fresh");
5811        fresh.id = "newer".into();
5812        fresh.priority = 100;
5813        for t in [&mut fresh, &mut later, &mut earlier] {
5814            q.put(t).unwrap();
5815        }
5816        let reloaded = Queue::at(q.root().to_owned());
5817        let mut tasks = reloaded.list();
5818        tasks.sort_unstable_by(dispatch_order);
5819        assert_eq!(
5820            tasks.iter().map(|t| t.id.as_str()).collect::<Vec<_>>(),
5821            vec!["earlier", "later", "newer"]
5822        );
5823        assert_eq!(reloaded.next_runnable().unwrap().id, "earlier");
5824        assert_eq!(reloaded.get("earlier").unwrap().attempts, 0);
5825    }
5826
5827    #[test]
5828    fn upgrade_resume_legacy_order_uses_settlement_and_id() {
5829        let mut a = upgrade_parked("a", "2026-10-22T00:00:02Z");
5830        let mut b = upgrade_parked("b", "2026-10-22T00:00:01Z");
5831        for t in [&mut a, &mut b] {
5832            let mut value = serde_json::to_value(&*t).unwrap();
5833            value["passes"][0]
5834                .as_object_mut()
5835                .unwrap()
5836                .remove("started_at");
5837            *t = serde_json::from_value(value).unwrap();
5838        }
5839        assert!(dispatch_order(&a, &b).is_lt());
5840        b.passes[0].settled_at = a.passes[0].settled_at;
5841        assert!(dispatch_order(&a, &b).is_lt());
5842    }
5843
5844    #[test]
5845    fn upgrade_resume_key_excludes_other_parks_and_explicit_task_changes() {
5846        let original = upgrade_parked("a", "2026-10-22T00:00:01Z");
5847        assert!(original.upgrade_resume_key().is_some());
5848        for cause in [
5849            crate::run::ParkCause::Operator,
5850            crate::run::ParkCause::Question,
5851            crate::run::ParkCause::Interrupt {
5852                reason: "interrupt".into(),
5853            },
5854            crate::run::ParkCause::Unspecified,
5855        ] {
5856            let mut t = original.clone();
5857            t.passes[0].parked = Some(cause);
5858            assert!(t.upgrade_resume_key().is_none());
5859            let mut fresh = task("fresh");
5860            fresh.priority = 1;
5861            assert!(dispatch_order(&fresh, &t).is_lt());
5862        }
5863        let mut t = original.clone();
5864        t.release();
5865        assert!(t.upgrade_resume_key().is_none());
5866        t.edit("edited".into(), "new instruction".into()).unwrap();
5867        assert!(t.upgrade_resume_key().is_none());
5868        let mut t = original.clone();
5869        t.requeue();
5870        t.status = TaskStatus::Parked;
5871        assert!(t.upgrade_resume_key().is_none());
5872        let mut t = original.clone();
5873        t.start("different-run".into());
5874        t.park("no upgrade");
5875        assert!(t.upgrade_resume_key().is_none());
5876    }
5877
5878    #[test]
5879    fn explicitly_resumed_older_run_becomes_current_without_duplicate_history() {
5880        let dir = tempfile::tempdir().unwrap();
5881        let q = Queue::at(dir.path().join("queue"));
5882        let mut t = task("resume");
5883        t.start("A".into());
5884        t.record_pass("A", 0, 1, None);
5885        t.start("B".into());
5886        q.put(&mut t).unwrap();
5887        assert_eq!(t.runs, vec!["A", "B"]);
5888        t.start("A".into());
5889        t.record_pass("A", 1, 3, None);
5890        q.put(&mut t).unwrap();
5891        let saved = q.get(&t.id).unwrap();
5892        assert_eq!(saved.runs, vec!["B", "A"]);
5893        assert_eq!(saved.runs.last().map(String::as_str), Some("A"));
5894        assert_eq!(saved.attempts, 3);
5895        assert_eq!(saved.passes.len(), 2);
5896        assert_eq!(saved.passes[0].run, "A");
5897        assert_eq!(saved.passes[1].run, "A");
5898    }
5899
5900    #[test]
5901    fn repeated_start_records_one_run_and_separate_passes() {
5902        let mut t = task("resume");
5903        t.start("same-run".into());
5904        t.record_pass("same-run", 0, 1, None);
5905        t.start("same-run".into());
5906        t.record_pass("same-run", 1, 2, None);
5907        assert_eq!(t.runs, vec!["same-run"]);
5908        assert_eq!(t.attempts, 2);
5909        assert_eq!(t.passes.len(), 2);
5910    }
5911
5912    #[test]
5913    fn link_run_adds_a_run_once_and_touches_nothing_else() {
5914        let dir = tempfile::tempdir().unwrap();
5915        let queue = Queue::at(dir.path().join("queue"));
5916        let mut t = Task::new(
5917            "t".to_owned(),
5918            "do it".to_owned(),
5919            PathBuf::from("."),
5920            Source::Human,
5921        );
5922        queue.put(&mut t).unwrap();
5923        let before = queue.get(&t.id).unwrap();
5924
5925        let linked = queue.link_run(&t.id[..4], "20260930-092817-ec34").unwrap();
5926        assert_eq!(linked.runs, vec!["20260930-092817-ec34".to_owned()]);
5927        assert_eq!(linked.status, before.status);
5928        assert_eq!(linked.attempts, before.attempts);
5929        assert_eq!(linked.interrupt, before.interrupt);
5930
5931        let again = queue.link_run(&t.id, "20260930-092817-ec34").unwrap();
5932        assert_eq!(again.runs.len(), 1, "linking twice must not duplicate");
5933        assert_eq!(queue.get(&t.id).unwrap().runs.len(), 1);
5934        assert!(queue.link_run("no-such-task", "r").is_err());
5935    }
5936
5937    #[test]
5938    fn put_keeps_a_run_linked_after_the_writer_took_its_snapshot() {
5939        let dir = tempfile::tempdir().unwrap();
5940        let queue = Queue::at(dir.path().join("queue"));
5941        let mut t = Task::new(
5942            "t".to_owned(),
5943            "do it".to_owned(),
5944            PathBuf::from("."),
5945            Source::Human,
5946        );
5947        queue.put(&mut t).unwrap();
5948        // The daemon's copy, taken before the link.
5949        let mut snapshot = queue.get(&t.id).unwrap();
5950        queue.link_run(&t.id, "20260930-092817-ec34").unwrap();
5951
5952        snapshot.start("20260930-000000-aaaa".to_owned());
5953        queue.put(&mut snapshot).unwrap();
5954
5955        let stored = queue.get(&t.id).unwrap();
5956        assert!(stored.runs.contains(&"20260930-092817-ec34".to_owned()));
5957        assert!(stored.runs.contains(&"20260930-000000-aaaa".to_owned()));
5958        assert_eq!(stored.attempts, 1);
5959    }
5960
5961    #[test]
5962    fn concurrent_links_and_daemon_saves_lose_nothing() {
5963        let dir = tempfile::tempdir().unwrap();
5964        let queue = Queue::at(dir.path().join("queue"));
5965        let mut t = Task::new(
5966            "t".to_owned(),
5967            "do it".to_owned(),
5968            PathBuf::from("."),
5969            Source::Human,
5970        );
5971        queue.put(&mut t).unwrap();
5972        let id = t.id.clone();
5973
5974        let linkers: Vec<_> = (0..4)
5975            .map(|n| {
5976                let (queue, id) = (queue.clone(), id.clone());
5977                std::thread::spawn(move || {
5978                    for k in 0..10 {
5979                        queue
5980                            .link_run(&id, &format!("20260930-00000{n}-l{k:03}"))
5981                            .unwrap();
5982                    }
5983                })
5984            })
5985            .collect();
5986        // The daemon's side: transitions saved from its own, ever staler,
5987        // copy of the task.
5988        let mut mine = queue.get(&id).unwrap();
5989        for k in 0..10 {
5990            mine.start(format!("20260930-000009-d{k:03}"));
5991            queue.put(&mut mine).unwrap();
5992        }
5993        for l in linkers {
5994            l.join().unwrap();
5995        }
5996
5997        let stored = queue.get(&id).unwrap();
5998        assert_eq!(stored.runs.len(), 50, "{:?}", stored.runs);
5999        assert_eq!(
6000            stored.attempts, 10,
6001            "linking never rewinds the daemon's work"
6002        );
6003    }
6004
6005    fn age_lock(path: &Path) {
6006        let f = std::fs::OpenOptions::new().write(true).open(path).unwrap();
6007        f.set_modified(std::time::SystemTime::now() - std::time::Duration::from_secs(60))
6008            .unwrap();
6009    }
6010
6011    #[test]
6012    fn concurrent_stale_takeover_yields_one_holder() {
6013        use std::sync::atomic::{AtomicUsize, Ordering};
6014        use std::sync::{Arc, Barrier};
6015        for _ in 0..5 {
6016            let dir = tempfile::tempdir().unwrap();
6017            let q = Queue::at(dir.path().to_path_buf());
6018            let lock = dir.path().join("t.write-lock");
6019            std::fs::write(&lock, "dead-0000").unwrap();
6020            age_lock(&lock);
6021            let n = 6;
6022            let barrier = Arc::new(Barrier::new(n));
6023            let (now, max) = (Arc::new(AtomicUsize::new(0)), Arc::new(AtomicUsize::new(0)));
6024            let handles: Vec<_> = (0..n)
6025                .map(|_| {
6026                    let (q, b, now, max) = (q.clone(), barrier.clone(), now.clone(), max.clone());
6027                    std::thread::spawn(move || {
6028                        b.wait();
6029                        let g = q.lock_task("t").unwrap();
6030                        let held = now.fetch_add(1, Ordering::SeqCst) + 1;
6031                        max.fetch_max(held, Ordering::SeqCst);
6032                        std::thread::sleep(std::time::Duration::from_millis(20));
6033                        now.fetch_sub(1, Ordering::SeqCst);
6034                        drop(g);
6035                    })
6036                })
6037                .collect();
6038            for h in handles {
6039                h.join().unwrap();
6040            }
6041            assert_eq!(max.load(Ordering::SeqCst), 1);
6042            assert!(!lock.exists());
6043        }
6044    }
6045
6046    #[test]
6047    fn dropping_a_replaced_lock_leaves_the_new_holders_token() {
6048        let dir = tempfile::tempdir().unwrap();
6049        let q = Queue::at(dir.path().to_path_buf());
6050        let lock = dir.path().join("t.write-lock");
6051        let a = q.lock_task("t").unwrap();
6052        // Simulate a foreign/legacy writer replacing the file. A modern
6053        // writer cannot acquire it while this guard's process is alive.
6054        let replacement = owner_token();
6055        std::fs::write(&lock, &replacement).unwrap();
6056        drop(a);
6057        assert_eq!(std::fs::read_to_string(&lock).unwrap(), replacement);
6058    }
6059
6060    #[test]
6061    fn aged_live_task_lock_excludes_updates_until_retirement_releases_it() {
6062        let dir = tempfile::tempdir().unwrap();
6063        let q = Queue::at(dir.path().to_path_buf());
6064        let held = q.lock_task("t").unwrap();
6065        let path = dir.path().join("t.write-lock");
6066        age_lock(&path);
6067        assert!(!break_stale(&path, &held.token));
6068        let (started_tx, started_rx) = std::sync::mpsc::channel();
6069        let (acquired_tx, acquired_rx) = std::sync::mpsc::channel();
6070        let updater = std::thread::spawn(move || {
6071            started_tx.send(()).unwrap();
6072            let _write = q.lock_task("t").unwrap();
6073            acquired_tx.send(()).unwrap();
6074        });
6075        started_rx.recv().unwrap();
6076        assert!(
6077            acquired_rx
6078                .recv_timeout(std::time::Duration::from_millis(100))
6079                .is_err()
6080        );
6081        assert_eq!(std::fs::read_to_string(&path).unwrap(), held.token);
6082        drop(held);
6083        acquired_rx
6084            .recv_timeout(std::time::Duration::from_secs(2))
6085            .unwrap();
6086        updater.join().unwrap();
6087        assert!(!path.exists());
6088    }
6089
6090    #[test]
6091    fn break_stale_leaves_a_lock_that_replaced_the_one_judged() {
6092        let dir = tempfile::tempdir().unwrap();
6093        let lock = dir.path().join("t.write-lock");
6094        std::fs::write(&lock, "new-token").unwrap();
6095        assert!(!break_stale(&lock, "old-token"));
6096        assert_eq!(std::fs::read_to_string(&lock).unwrap(), "new-token");
6097        // Same token but fresh: not stale any more, so also left alone.
6098        assert!(!break_stale(&lock, "new-token"));
6099        assert!(lock.exists());
6100        age_lock(&lock);
6101        assert!(break_stale(&lock, "new-token"));
6102        assert!(!lock.exists());
6103    }
6104
6105    #[test]
6106    fn a_stale_break_marker_is_recovered_and_a_fresh_one_is_respected() {
6107        let dir = tempfile::tempdir().unwrap();
6108        let lock = dir.path().join("t.write-lock");
6109        std::fs::write(&lock, "dead-1").unwrap();
6110        age_lock(&lock);
6111        let marker = break_marker(&lock, "dead-1");
6112        std::fs::write(&marker, "crashed-remover").unwrap();
6113        // Fresh marker: another remover is working, so nothing is broken.
6114        assert!(!break_stale(&lock, "dead-1"));
6115        assert!(lock.exists());
6116        // Stale marker: recovered, then the lock is broken.
6117        age_lock(&marker);
6118        assert!(break_stale(&lock, "dead-1"));
6119        assert!(!lock.exists());
6120        assert!(!marker.exists());
6121    }
6122
6123    fn chat_task() -> Task {
6124        Task::new(
6125            "t".to_owned(),
6126            "do t".to_owned(),
6127            PathBuf::from("."),
6128            Source::Agent {
6129                run: "20260902-000000-beef".to_owned(),
6130                node: CHAT_NODE.to_owned(),
6131            },
6132        )
6133    }
6134
6135    #[test]
6136    fn a_blocked_hold_keeps_its_anchor_but_a_new_run_starts_a_new_hold() {
6137        let mut t = chat_task();
6138        t.hold_machine(Some("waiting".into()));
6139        let old: Timestamp = "2020-01-01T00:00:00Z".parse().unwrap();
6140        t.held_at = Some(old);
6141        t.block(vec!["decision".into()], None);
6142        t.hold_machine(Some("same waiting decision".into()));
6143        assert_eq!(t.held_at, Some(old));
6144        t.start("real-new-run".into());
6145        t.fail("new failure", 1);
6146        assert_ne!(
6147            t.held_at,
6148            Some(old),
6149            "old answers cannot approve a new hold"
6150        );
6151    }
6152
6153    #[test]
6154    fn legacy_delivery_survives_upgrade_and_a_no_progress_run_link() {
6155        let (_dir, queue) = queue();
6156        let mut t = chat_task();
6157        t.start("old-run".into());
6158        t.hold_machine(Some("operator is considering recovery".into()));
6159        t.chat_notice = Some(ChatNotice {
6160            key: format!("held#{}", t.held_at.unwrap()),
6161            at: Timestamp::now(),
6162            outcome: ChatNoticeOutcome::Posted,
6163        });
6164        let mut raw = serde_json::to_value(&t).unwrap();
6165        raw.as_object_mut().unwrap().remove("chat_notices");
6166        raw.as_object_mut().unwrap().remove("hold_notice_cause");
6167        std::fs::create_dir_all(queue.path_of(&t.id).parent().unwrap()).unwrap();
6168        std::fs::write(queue.path_of(&t.id), serde_json::to_string(&raw).unwrap()).unwrap();
6169        assert_eq!(queue.get(&t.id).unwrap().chat_notice_due(), None);
6170        queue
6171            .modify(&t.id, |task| {
6172                task.requeue();
6173                task.link_run("unprepared-run");
6174                task.startup_notice_cause("startup-source");
6175                task.fail("same unresolved preflight", 0);
6176                true
6177            })
6178            .unwrap();
6179        assert_eq!(queue.get(&t.id).unwrap().chat_notice_due(), None);
6180        queue
6181            .modify(&t.id, |task| {
6182                task.succeed();
6183                true
6184            })
6185            .unwrap();
6186        assert_eq!(
6187            queue.get(&t.id).unwrap().chat_notice_due().as_deref(),
6188            Some("done")
6189        );
6190    }
6191
6192    #[test]
6193    fn a_dependency_wait_does_not_change_when_released_and_blocked_again() {
6194        let mut t = chat_task();
6195        t.block(vec!["a".into(), "b".into()], Some("waiting".into()));
6196        let key = t.chat_notice_key().unwrap();
6197        t.chat_notices.push(key);
6198        t.release();
6199        t.block(
6200            vec!["b".into(), "a".into(), "a".into()],
6201            Some("still waiting on prerequisites".into()),
6202        );
6203        assert_eq!(t.chat_notice_due(), None);
6204        t.block(
6205            vec!["new-question".into()],
6206            Some("different decision".into()),
6207        );
6208        assert!(t.chat_notice_due().is_some());
6209    }
6210
6211    #[test]
6212    fn running_startup_failures_preserve_stage_and_report_distinct_blockers() {
6213        let mut t = chat_task();
6214        t.start("existing-run".into());
6215        t.fail("implementation failed", 1);
6216        let failed = t.chat_notice_key().unwrap();
6217        t.chat_notices.push(failed.clone());
6218        t.release_operator("test", None);
6219        t.start("existing-run".into());
6220        t.fail_startup("startup-source", "same unresolved recovery source", 1);
6221        assert_eq!(
6222            t.chat_notice_due(),
6223            None,
6224            "no-progress recovery stays quiet"
6225        );
6226        t.release_operator("test", None);
6227        t.start("existing-run".into());
6228        t.fail_startup("startup-attachments", "attachment missing", 1);
6229        let attachments = t.chat_notice_due().expect("new attachment blocker");
6230        assert_ne!(attachments, failed);
6231        assert_eq!(
6232            t.hold_notice_cause.as_ref().unwrap().stage,
6233            "startup-attachments"
6234        );
6235        t.chat_notices.push(attachments);
6236        t.release_operator("test", None);
6237        t.start("existing-run".into());
6238        t.fail_startup(
6239            "startup-attachments",
6240            "same missing attachment, reworded",
6241            1,
6242        );
6243        assert_eq!(
6244            t.chat_notice_due(),
6245            None,
6246            "same stage after attempt counter reset"
6247        );
6248        t.release_operator("test", None);
6249        t.start("existing-run".into());
6250        t.fail_startup("startup-config", "different preflight stage", 1);
6251        assert!(t.chat_notice_due().is_some());
6252        assert_eq!(
6253            t.hold_notice_cause.as_ref().unwrap().stage,
6254            "startup-config"
6255        );
6256    }
6257
6258    #[test]
6259    fn structured_causes_preserve_no_progress_retries_and_report_new_passes() {
6260        let mut t = chat_task();
6261        t.hold_machine(Some("startup source missing".into()));
6262        t.startup_notice_cause("startup-source");
6263        let first = t.chat_notice_key().unwrap();
6264        t.chat_notices.push(first.clone());
6265        t.release_operator("test", None);
6266        t.startup_notice_cause("startup-source");
6267        t.hold_machine(Some("same source cannot be read".into()));
6268        assert_eq!(t.chat_notice_due(), None);
6269        t.startup_notice_cause("startup-config");
6270        assert!(t.chat_notice_due().is_some(), "different startup stage");
6271        t.notice_cause("failed", Some("existing-run"), Some(0));
6272        let run_failure = t.chat_notice_key().unwrap();
6273        t.chat_notices.push(run_failure.clone());
6274        t.release_operator("test", None);
6275        t.startup_notice_cause("startup-source");
6276        t.hold_machine(Some("no new work happened".into()));
6277        assert_eq!(t.chat_notice_due(), None);
6278        t.notice_cause("failed", Some("existing-run"), Some(1));
6279        assert!(t.chat_notice_due().is_some(), "a real resumed pass failed");
6280        assert_ne!(t.chat_notice_key().unwrap(), run_failure);
6281    }
6282
6283    #[test]
6284    fn legacy_hold_baseline_does_not_replay_or_hide_new_failures_and_completion() {
6285        let mut t = chat_task();
6286        t.hold_machine(Some("still waiting".into()));
6287        t.chat_notice = Some(ChatNotice {
6288            key: "held#2026-10-14T00:00:00Z".into(),
6289            at: Timestamp::now(),
6290            outcome: ChatNoticeOutcome::Posted,
6291        });
6292        assert_eq!(t.chat_notice_due(), None, "old hold baseline");
6293        t.import_chat_notice();
6294        t.notice_cause("failed", Some("new-run"), Some(0));
6295        assert!(t.chat_notice_due().is_some(), "new producer evidence");
6296        t.succeed();
6297        assert_eq!(t.chat_notice_due().as_deref(), Some("done"));
6298    }
6299
6300    #[test]
6301    fn a_chat_notice_is_due_only_for_a_final_state_and_only_once() {
6302        let mut t = chat_task();
6303        assert_eq!(t.chat_notice_due(), None, "queued");
6304        t.start("r1".to_owned());
6305        assert_eq!(t.chat_notice_due(), None, "running");
6306        t.fail("boom", 3);
6307        assert_eq!(t.status, TaskStatus::Failed);
6308        assert_eq!(t.chat_notice_due(), None, "a retried failure is not final");
6309        t.start("r2".to_owned());
6310        t.park("upgrade");
6311        assert_eq!(t.chat_notice_due(), None, "parked");
6312        t.fail("boom", 1);
6313        assert_eq!(t.status, TaskStatus::Held);
6314        let key = t
6315            .chat_notice_due()
6316            .expect("held on the last attempt is final");
6317        t.chat_notice = Some(ChatNotice {
6318            key,
6319            at: Timestamp::now(),
6320            outcome: ChatNoticeOutcome::Posted,
6321        });
6322        assert_eq!(t.chat_notice_due(), None, "same hold, no second notice");
6323        t.release();
6324        assert_eq!(t.chat_notice_due(), None, "requeued after a release");
6325        t.start("r3".to_owned());
6326        t.succeed();
6327        assert!(t.chat_notice_due().is_some(), "done is a new final state");
6328    }
6329
6330    #[test]
6331    fn completed_chat_notices_keep_current_and_legacy_keys_after_requeue() {
6332        for key in ["done", "done#0", "done#1", "done#12"] {
6333            let mut t = chat_task();
6334            t.start("r1".to_owned());
6335            t.succeed();
6336            t.chat_notice = Some(ChatNotice {
6337                key: key.to_owned(),
6338                at: Timestamp::now(),
6339                outcome: ChatNoticeOutcome::Posted,
6340            });
6341            t.requeue();
6342            t.start("r2".to_owned());
6343            t.succeed();
6344            assert_eq!(t.chat_notice_key().as_deref(), Some("done"));
6345            assert_eq!(t.chat_notice_due(), None, "recorded key: {key}");
6346        }
6347    }
6348
6349    #[test]
6350    fn a_release_without_progress_keeps_the_unresolved_notice_cause() {
6351        let mut t = chat_task();
6352        t.hold_manual(Some("wait".to_owned()));
6353        let first = t.chat_notice_due().expect("held");
6354        t.chat_notice = Some(ChatNotice {
6355            key: first.clone(),
6356            at: Timestamp::now(),
6357            outcome: ChatNoticeOutcome::Posted,
6358        });
6359        t.hold_manual(Some("still waiting".to_owned()));
6360        assert_eq!(t.chat_notice_due(), None, "a re-hold keeps its start");
6361        t.release();
6362        std::thread::sleep(std::time::Duration::from_millis(5));
6363        t.hold_manual(None);
6364        assert_eq!(t.chat_notice_due(), None, "no progress, same cause");
6365    }
6366
6367    #[test]
6368    fn a_chat_notice_needs_a_chat_source_and_a_current_schema() {
6369        let mut human = task("h");
6370        human.succeed();
6371        assert_eq!(human.chat_notice_due(), None);
6372        // A follow-up only inherits the chat; it did not file the task.
6373        let mut inherited = task("i");
6374        inherited.origin_chat = Some("20260902-000000-beef".to_owned());
6375        inherited.succeed();
6376        assert_eq!(inherited.chat_notice_due(), None);
6377        let mut old = chat_task();
6378        old.schema = 12;
6379        old.status = TaskStatus::Done;
6380        assert_eq!(old.chat_notice_due(), None, "history is not replayed");
6381        let mut live = chat_task();
6382        live.schema = 12;
6383        live.start("r1".to_owned());
6384        live.succeed();
6385        assert!(live.chat_notice_due().is_some(), "started by this build");
6386        let mut held = chat_task();
6387        held.schema = 12;
6388        held.hold_machine(Some("config".to_owned()));
6389        assert!(held.chat_notice_due().is_some(), "held before any start");
6390    }
6391
6392    #[test]
6393    fn a_stale_snapshot_does_not_rewind_a_recorded_chat_notice() {
6394        let tmp = tempfile::tempdir().expect("tempdir");
6395        let q = Queue::at(tmp.path().join("queue"));
6396        let mut t = chat_task();
6397        t.succeed();
6398        q.put(&mut t).expect("put");
6399        let mut stale = q.get(&t.id).expect("get");
6400        let key = t.chat_notice_due().expect("due");
6401        q.modify(&t.id, |x| {
6402            x.chat_notice = Some(ChatNotice {
6403                key: key.clone(),
6404                at: Timestamp::now(),
6405                outcome: ChatNoticeOutcome::Posted,
6406            });
6407            true
6408        })
6409        .expect("modify");
6410        q.put(&mut stale).expect("stale put");
6411        assert_eq!(q.get(&t.id).expect("get").chat_notice_due(), None);
6412    }
6413
6414    #[test]
6415    fn empty_sources_are_omitted_so_older_builds_still_read_the_task() {
6416        // `Task` rejects unknown fields, so a build without `sources` cannot
6417        // read a record that carries the key, even an empty one.
6418        let mut t = task("plain");
6419        let value = serde_json::to_value(&t).unwrap();
6420        assert!(value.get("sources").is_none(), "{value}");
6421        t.sources.pick_commits.push(crate::refs::Input {
6422            token: "abc1234".into(),
6423            sha: "a".repeat(40),
6424            provenance: crate::refs::Provenance::ExplicitCli,
6425        });
6426        let value = serde_json::to_value(&t).unwrap();
6427        assert_eq!(value["sources"]["pick_commits"][0]["sha"], "a".repeat(40));
6428        let restored: Task = serde_json::from_value(value).unwrap();
6429        assert_eq!(restored.sources, t.sources);
6430    }
6431
6432    /// A queue whose id source yields `ids` in order, then fresh ones.
6433    fn queue_with_ids(dir: &Path, ids: &[&str]) -> Queue {
6434        let ids: Vec<String> = ids.iter().map(|s| (*s).to_owned()).collect();
6435        let n = std::sync::atomic::AtomicUsize::new(0);
6436        Queue::at(dir.join("queue")).with_id_source(move || {
6437            let i = n.fetch_add(1, std::sync::atomic::Ordering::SeqCst);
6438            ids.get(i)
6439                .cloned()
6440                .unwrap_or_else(|| format!("20260101-000000-f{i:03x}"))
6441        })
6442    }
6443
6444    const TAKEN: &str = "20260101-000000-aaaa";
6445
6446    #[test]
6447    fn a_new_task_never_merges_into_a_record_with_its_candidate_id() {
6448        let dir = tempfile::tempdir().unwrap();
6449        let q = queue_with_ids(dir.path(), &[TAKEN, TAKEN]);
6450        let mut first = task("first");
6451        first.start("run-1".into());
6452        first.succeed();
6453        q.put(&mut first).unwrap();
6454        assert_eq!(first.id, TAKEN);
6455        let stored_before = q.get(&first.id).unwrap();
6456        assert!(!stored_before.runs.is_empty());
6457
6458        let mut second = task("second");
6459        q.put(&mut second).unwrap();
6460
6461        assert_ne!(second.id, first.id);
6462        assert!(second.runs.is_empty());
6463        assert!(second.passes.is_empty());
6464        assert!(second.chat_notices.is_empty());
6465        assert!(second.chat_notice.is_none());
6466        assert_eq!(second.chat_notice_due(), task("fresh").chat_notice_due());
6467        let a = q.get(&first.id).unwrap();
6468        let b = q.get(&second.id).unwrap();
6469        assert_eq!(a.title, "first");
6470        assert_eq!(a.runs, stored_before.runs);
6471        assert_eq!(a.passes, stored_before.passes);
6472        assert_eq!(a.chat_notices, stored_before.chat_notices);
6473        assert_eq!(a.chat_notice, stored_before.chat_notice);
6474        assert_eq!(a.chat_notice_due(), stored_before.chat_notice_due());
6475        assert_eq!(b.title, "second");
6476        assert!(b.runs.is_empty());
6477        assert!(b.passes.is_empty());
6478        assert!(b.chat_notice.is_none());
6479
6480        // A later save is an update: it still merges.
6481        let mut again = q.get(&second.id).unwrap();
6482        again.title = "second, edited".into();
6483        q.put(&mut again).unwrap();
6484        assert_eq!(q.get(&second.id).unwrap().title, "second, edited");
6485        assert_eq!(q.list().len(), 2);
6486    }
6487
6488    #[test]
6489    fn a_new_task_skips_an_id_with_an_orphaned_claim_or_attachments() {
6490        let dir = tempfile::tempdir().unwrap();
6491        let q = queue_with_ids(dir.path(), &["orphan-lock", "orphan-dir", "free"]);
6492        std::fs::create_dir_all(q.root()).unwrap();
6493        std::fs::write(q.root().join("orphan-lock.lock"), "x").unwrap();
6494        std::fs::create_dir_all(q.attachments_dir("orphan-dir")).unwrap();
6495        let mut t = task("t");
6496        q.put(&mut t).unwrap();
6497        assert_eq!(t.id, "free");
6498    }
6499
6500    #[test]
6501    fn a_claimed_new_task_holds_the_claim_on_the_reserved_id() {
6502        let dir = tempfile::tempdir().unwrap();
6503        let q = queue_with_ids(dir.path(), &[TAKEN, TAKEN]);
6504        let mut first = task("first");
6505        q.put(&mut first).unwrap();
6506        let mut second = task("second");
6507        let claim = q.file_claimed(&mut second).unwrap();
6508        assert_ne!(second.id, first.id);
6509        assert!(q.claim(&second.id).is_err());
6510        assert!(q.claim(&first.id).is_ok(), "the first task was not claimed");
6511        drop(claim);
6512    }
6513
6514    #[test]
6515    fn an_attached_new_task_skips_a_taken_id() {
6516        let dir = tempfile::tempdir().unwrap();
6517        let q = queue_with_ids(dir.path(), &[TAKEN, TAKEN]);
6518        let mut first = task("first");
6519        q.put(&mut first).unwrap();
6520        let src = source_file(dir.path(), "shot.png", "x");
6521        let mut second = task("second");
6522        q.attach_and_put(&mut second, &[src]).unwrap();
6523        assert_ne!(second.id, first.id);
6524        assert!(!q.attachments_dir(&first.id).exists());
6525        assert_eq!(q.attachment_paths(&second).len(), 1);
6526        assert!(q.attachment_paths(&second)[0].is_file());
6527    }
6528
6529    #[test]
6530    fn attaching_before_putting_a_new_task_reserves_the_id() {
6531        let dir = tempfile::tempdir().unwrap();
6532        let q = queue_with_ids(dir.path(), &[TAKEN, TAKEN]);
6533        let mut first = task("first");
6534        q.put(&mut first).unwrap();
6535        let src = source_file(dir.path(), "shot.png", "x");
6536        let mut second = task("second");
6537        q.attach(&mut second, &[src]).unwrap();
6538        assert_ne!(second.id, first.id);
6539        assert!(q.attachments_dir(&second.id).is_dir());
6540        q.put(&mut second).unwrap();
6541        assert_eq!(q.get(&second.id).unwrap().attachments.len(), 1);
6542        assert_eq!(q.get(&first.id).unwrap().title, "first");
6543        assert!(q.get(&first.id).unwrap().attachments.is_empty());
6544    }
6545
6546    #[test]
6547    fn create_new_keeps_its_already_exists_meaning() {
6548        let dir = tempfile::tempdir().unwrap();
6549        let q = Queue::at(dir.path().join("queue"));
6550        let mut a = task("a");
6551        a.id = "fixed-id".into();
6552        assert!(q.create_new(&mut a).unwrap());
6553        let mut b = task("b");
6554        b.id = "fixed-id".into();
6555        assert!(!q.create_new(&mut b).unwrap());
6556        assert_eq!(q.get("fixed-id").unwrap().title, "a");
6557    }
6558
6559    #[test]
6560    fn filing_gives_up_when_no_id_is_ever_free() {
6561        let dir = tempfile::tempdir().unwrap();
6562        let q = Queue::at(dir.path().join("queue")).with_id_source(|| TAKEN.to_owned());
6563        let mut first = task("first");
6564        q.put(&mut first).unwrap();
6565        let mut second = task("second");
6566        assert!(q.put(&mut second).is_err());
6567        assert_eq!(q.get(&first.id).unwrap().title, "first");
6568    }
6569}