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