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