shep-daemon 0.18.2

The supervision engine behind shep: process spawning, restart policy, the log plane, watch and cron restarts, and the RPC server
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
//! Reading and writing one sheep's config from a pane.
//!
//! An operator editing a single sheep is not the same as loading a
//! Flockfile: the change is theirs, it outlives the next load, and it is
//! stored as an override. The handlers here answer a pane's read and take its
//! writes, one field or a batch of environment variables at a time.

use super::*;

/// Records one env edit in `record`: `value` under `key`, or with `None` the
/// removal of `key`, leaving a tombstone where the removal is the only record
/// of it.
///
/// `was_in_config` is whether the intended config held `key` before the edit,
/// which a removal needs to know whether there was anything to remove.
///
/// # Errors
///
/// [`SupervisorError::Overrides`] - the stored `env` override is not an
/// object.
pub(super) fn record_env_edit(
    record: &mut AppOverrides,
    name: &str,
    key: &str,
    value: Option<&str>,
    was_in_config: bool,
) -> Result<(), SupervisorError> {
    // Read before `env_override_map` borrows the record mutably.
    let file_declares = record.declared_env.contains(key);
    let map = env_override_map(&mut *record, name)?;
    let was_overridden = map.contains_key(key);
    // A tombstone is left alone rather than removed and re-inserted,
    // which makes a second removal of the same key a no-op instead of
    // a deletion. Without this, removing an already-removed key drops
    // the tombstone (there is nothing in the config to remove, so the
    // re-insert below does not fire) and the next load of a file that
    // still declares the key puts its value back.
    let tombstoned = map.get(key).is_some_and(serde_json::Value::is_null);
    match value {
        Some(value) => map.insert(
            key.to_string(),
            serde_json::Value::String(value.to_string()),
        ),
        None if tombstoned => None,
        None => map.remove(key),
    };
    // Dropping the operator's own value is only half an answer: for a
    // key the operator never set, `map.remove` is a no-op, the store
    // comes back `{}`, and the edit lives only in
    // `ProcessEntry::pending`, lost to a cold restart and invisible in
    // the CFG column.
    //
    // So a removal leaves a JSON `null` tombstone under the key
    // whenever the key was in the config and something other than
    // this store put it there. Three cases fall out of the condition
    // below:
    //
    // - the key came from the app's config and was never overridden:
    //   tombstone, since the removal is the operator's only record of
    //   it;
    // - the key was an operator override the file also declares:
    //   tombstone, since dropping the override alone would let the
    //   file's value read as current;
    // - the key was an operator override and nothing else supplies
    //   it: plain removal, since the sheep now matches its file. A
    //   tombstone here would mark a sheep forever for a key that
    //   exists nowhere.
    //
    // A null never becomes a config value: `merge_declared`'s env
    // branch reads this map for its keys only, so a null just marks
    // "somebody has spoken for this key" and stops a later plain load
    // from restoring it. `--reset=env` and `--reset=all` clear it
    // through `merge_declared`'s own `next.fields.remove("env")`, not
    // through `establish_env`, which by then has nothing left to find
    // and deliberately preserves a tombstone it does find.
    if value.is_none() && was_in_config && (!was_overridden || file_declares) {
        map.insert(key.to_string(), serde_json::Value::Null);
    }
    let emptied = map.is_empty();
    // A removal that left nothing behind takes the `env` key with it,
    // for the reason `merge_declared` states where it spends an
    // override: a field nobody is holding a value for must stop
    // reporting in `ProcessEntry::overridden`, or the CFG column
    // marks a sheep that no longer differs from its Flockfile.
    if emptied {
        record.fields.remove("env");
    }
    Ok(())
}

impl<R: ProcessRunner> Actor<R> {
    /// Refuse `name` when the slot at `id` is a dog's.
    ///
    /// A dog runs at the daemon's own trust level and its binary is what
    /// `shep adopt` vetted, so a `PATH`, an `LD_PRELOAD` or a
    /// `DYLD_INSERT_LIBRARIES` parked for its next respawn is arbitrary code
    /// at that level. A dog is never in the override store, so nothing further
    /// down any of these doors would have caught it, which is why every caller
    /// asks before the store is read.
    ///
    /// # Errors
    ///
    /// [`SupervisorError::IsADog`] - the slot at `id` is a dog's.
    pub(super) fn ensure_not_dog(&self, name: &str, id: u32) -> Result<(), SupervisorError> {
        if self
            .sheep
            .get(&id)
            .is_some_and(|slot| slot.entry.dog.is_some())
        {
            return Err(SupervisorError::IsADog(dog_config_refusal(name)));
        }
        Ok(())
    }

    /// One read-modify-write of `name`'s record in the override store, and
    /// the field names it leaves overridden.
    ///
    /// `f` is the mutation, which is the only part of a pane write that is
    /// not this: the store read, the empty record a first edit needs, the
    /// field names an operator has spoken for, and the one-record write back.
    /// A refusal out of `f` lands before the store is written, so a config
    /// this build will not take leaves no record behind.
    ///
    /// # Errors
    ///
    /// - [`SupervisorError::Overrides`] - the store could not be read or
    ///   written.
    /// - Whatever `f` refuses.
    pub(super) fn mutate_override(
        &self,
        name: &str,
        f: impl FnOnce(&mut AppOverrides) -> Result<(), SupervisorError>,
    ) -> Result<Vec<String>, SupervisorError> {
        let mut record = overrides::get(&self.paths.overrides, name)
            .map_err(|err| SupervisorError::Overrides(err.to_string()))?
            .unwrap_or_default();
        f(&mut record)?;
        let overridden: Vec<String> = record.fields.keys().cloned().collect();
        let changes = BTreeMap::from([(name.to_string(), Some(record))]);
        overrides::update(&self.paths.overrides, &changes)
            .map_err(|err| SupervisorError::Overrides(err.to_string()))?;
        Ok(overridden)
    }

    /// Park `parked` on every slot of `name`, with `overridden` beside it.
    ///
    /// Exactly what [`Self::apply_one`] writes for one, and `ids_of_name`
    /// re-read for its reason too. A caller that also moves `spec` or
    /// `pending_reidentifies` writes its own loop: an env key never makes a
    /// `user`/`group` move, and a config field can.
    pub(super) fn park_slots(&mut self, name: &str, parked: &ResolvedApp, overridden: &[String]) {
        for id in self.ids_of_name(name) {
            let Some(slot) = self.sheep.get_mut(&id) else {
                continue;
            };
            slot.entry.pending = Some(parked.clone());
            slot.entry.overridden = overridden.to_vec();
        }
    }

    /// One sheep's effective config for a pane, or `Ok(None)` when no sheep
    /// has that name.
    ///
    /// Reads and writes nothing. `env` is emptied on the way out by
    /// [`SheepConfigView::new`], which is the only constructor, so no path
    /// out of here can carry a value.
    ///
    /// # Errors
    ///
    /// - [`SupervisorError::IsADog`] - the name is a dog's. No other
    ///   request hands a client a whole `AppConfig`, so serving one here
    ///   would be a read surface that exists for dogs and nothing else.
    pub(super) fn handle_sheep_config(
        &self,
        name: &str,
    ) -> Result<Option<SheepConfigView>, SupervisorError> {
        let Some(id) = self.representative_id(name) else {
            return Ok(None);
        };
        self.ensure_not_dog(name, id)?;
        let Some(slot) = self.sheep.get(&id) else {
            return Ok(None);
        };
        // [`Self::intended_spec`], not the running `spec`: a pane has to
        // show what the sheep is meant to be, or an operator's own parked
        // edit reads as never having landed. `pending` beside it is what
        // says the running child does not have it yet, and it is computed
        // off the same helper the listing uses, so the pane and the flock
        // table never disagree about the same sheep.
        let Some(config) = self.intended_spec(id).map(|spec| spec.config().clone()) else {
            return Ok(None);
        };
        Ok(Some(SheepConfigView::new(
            config,
            self.overridden_for(name),
            pending_fields(&slot.entry),
        )))
    }

    /// Records `key` on `name`'s env as an operator override, or removes it
    /// with `value: None`, and parks the result for that sheep's next spawn.
    ///
    /// `Ok(false)` when no sheep has that name.
    ///
    /// # Ordering
    ///
    /// Validate, then write the store, then park. A refusal is therefore
    /// raised before anything is touched, so an operator whose key
    /// `normalize` will not take is left with the env they already had
    /// rather than a store that disagrees with the flock.
    ///
    /// # Why it parks rather than applies
    ///
    /// The running child was handed its environment at `execve` and cannot
    /// be handed another one, so `env` is a `NeedsRespawn` field wherever it
    /// appears (`config::apply`'s table) and this takes the same route
    /// [`Self::apply_one`] takes for one: onto every slot's
    /// [`ProcessEntry::pending`], for a `shep reload` or `shep restart` to
    /// promote.
    ///
    /// # Errors
    ///
    /// - [`SupervisorError::IsADog`] - the name is a dog's. Raised before
    ///   the store is read, so nothing was written.
    /// - [`SupervisorError::InvalidEnv`] - the resulting config is one
    ///   `normalize` refuses. Nothing was written.
    /// - [`SupervisorError::Overrides`] - the override store could not be
    ///   read or written. Nothing was parked.
    pub(super) fn handle_set_sheep_env(
        &mut self,
        name: &str,
        key: &str,
        value: Option<&str>,
    ) -> Result<Option<ResolvedApp>, SupervisorError> {
        let Some(id) = self.representative_id(name) else {
            return Ok(None);
        };
        // Before the store is read, and long before it is written:
        // [`Self::ensure_not_dog`] is why, and [`Self::apply_one`] refuses a
        // Flockfile that names a dog with the same sentence.
        self.ensure_not_dog(name, id)?;
        // The config an unchanged next spawn would use, which is a parked
        // one when an earlier load left one: building on the running config
        // instead would drop that load's change on the floor, which is
        // `apply_one`'s own reason for reading `intended` rather than
        // `running`.
        let Some(mut intended) = self.intended_spec(id).map(|spec| spec.config().clone()) else {
            return Ok(None);
        };
        // Captured before the edit, because the removal branch below needs
        // to know whether there was anything to remove.
        let was_in_config = intended.env.contains_key(key);
        match value {
            Some(value) => intended.env.insert(key.to_string(), value.to_string()),
            None => intended.env.remove(key),
        };

        let parked =
            normalize(intended).map_err(|err| SupervisorError::InvalidEnv(err.to_string()))?;

        let overridden = self.mutate_override(name, |record| {
            record_env_edit(record, name, key, value, was_in_config)
        })?;

        self.park_slots(name, &parked, &overridden);
        Ok(Some(parked))
    }

    /// Records several env keys on `name` as operator overrides in one
    /// write, and parks them for the next spawn.
    ///
    /// `Ok(None)` when no sheep has that name.
    ///
    /// # Why this is not a loop over [`Self::handle_set_sheep_env`]
    ///
    /// That function writes the store once per key. Twenty keys would be
    /// twenty read-modify-writes, and a failure at the eleventh would leave
    /// half an import applied with no record of which half. This validates
    /// every key against the intended config first, then writes once.
    ///
    /// # Collisions
    ///
    /// A key already holding a different value in the intended config
    /// collides. Without `force`, one collision refuses the whole batch and
    /// nothing is written. A key holding the same value is `unchanged` and
    /// is not rewritten, so a repeated identical batch is a no-op.
    ///
    /// # What a dry run answers
    ///
    /// Everything the real send would, refusals included: `normalize` runs
    /// on the merged config before this returns, so a preview that reports
    /// a key as `set` is one the real send takes. `app` is `None` here, as
    /// it is for a refused batch and for one whose keys were all
    /// `unchanged`: nothing was written for the caller to record.
    ///
    /// # Errors
    ///
    /// - [`SupervisorError::IsADog`] - the name is a dog's. Raised before
    ///   the store is read, for [`Self::handle_set_sheep_env`]'s reason.
    /// - [`SupervisorError::InvalidEnv`] - the resulting config is one
    ///   `normalize` refuses. Nothing was written, on a dry run or a real
    ///   send alike.
    /// - [`SupervisorError::Overrides`] - the store could not be read or
    ///   written. Nothing was parked.
    pub(super) fn handle_set_sheep_env_batch(
        &mut self,
        name: &str,
        entries: &BTreeMap<String, String>,
        force: bool,
        dry_run: bool,
    ) -> Result<Option<EnvBatch>, SupervisorError> {
        let Some(id) = self.representative_id(name) else {
            return Ok(None);
        };
        // Before the store is read, for [`Self::ensure_not_dog`]'s reason.
        self.ensure_not_dog(name, id)?;
        let Some(mut intended) = self.intended_spec(id).map(|spec| spec.config().clone()) else {
            return Ok(None);
        };

        let mut set = Vec::new();
        let mut unchanged = Vec::new();
        let mut collisions = Vec::new();
        for (key, value) in entries {
            match intended.env.get(key) {
                Some(current) if current == value => unchanged.push(key.clone()),
                Some(_) => {
                    collisions.push(key.clone());
                    if force {
                        set.push(key.clone());
                    }
                }
                None => set.push(key.clone()),
            }
        }

        // A refused batch changes nothing, so what the merged config would
        // normalize to is moot and the collision report is the whole answer.
        if !collisions.is_empty() && !force {
            return Ok(Some(EnvBatch {
                app: None,
                set: Vec::new(),
                unchanged,
                collisions,
            }));
        }

        // Before the `dry_run` return, not after it: `normalize` is this
        // door's only validation, so a preview that skipped it would report
        // a key as `set` and then fail on the real send.
        for key in &set {
            intended.env.insert(key.clone(), entries[key].clone());
        }
        let parked =
            normalize(intended).map_err(|err| SupervisorError::InvalidEnv(err.to_string()))?;

        // `set` empty means every key was already held at this value, so
        // there is nothing to write and nothing for `rpc/dispatch.rs` to record:
        // `app` is `Some` only when the store moved.
        if dry_run || set.is_empty() {
            return Ok(Some(EnvBatch {
                app: None,
                set,
                unchanged,
                collisions,
            }));
        }

        let overridden = self.mutate_override(name, |record| {
            let map = env_override_map(&mut *record, name)?;
            for key in &set {
                map.insert(key.clone(), serde_json::Value::String(entries[key].clone()));
            }
            // No tombstone handling and no `emptied` branch: this door only
            // ever inserts, so the map cannot come out empty and no key can
            // stop being held.
            Ok(())
        })?;

        self.park_slots(name, &parked, &overridden);
        Ok(Some(EnvBatch {
            app: Some(parked),
            set,
            unchanged,
            collisions,
        }))
    }

    /// A pane's door to [`Self::write_sheep_field`]: refuses the keys
    /// another request owns, then writes.
    ///
    /// # Errors
    ///
    /// - [`SupervisorError::InvalidField`] - `env`, `dogs`, or a
    ///   Structural key. Nothing was read or written.
    /// - Whatever [`Self::write_sheep_field`] refuses.
    pub(super) fn handle_set_sheep_field(
        &mut self,
        name: &str,
        key: &str,
        value: &serde_json::Value,
    ) -> Result<Option<FieldSet>, SupervisorError> {
        refuse_unowned_key(key)?;
        self.write_sheep_field(name, key, value)
    }

    /// Drops the operator's override of `key` on `name`, so the value it held
    /// before comes back, and applies or parks that value as
    /// [`Self::write_sheep_field`] does.
    ///
    /// The value that returns is the override record's `template` for the key:
    /// the Flockfile's value as of the last load that named it, or the value
    /// the sheep held when the operator first spoke for it. A record written
    /// before that was kept has none, and the key goes back to the built-in
    /// default, which is the value a pane's `d` restores too.
    ///
    /// `Ok(None)` when no sheep has that name.
    ///
    /// # Errors
    ///
    /// - [`SupervisorError::InvalidField`] - the key is one
    ///   [`Self::handle_set_sheep_field`] refuses, or the operator has not
    ///   overridden it, or the value it goes back to will not normalize.
    ///   Nothing was written.
    /// - [`SupervisorError::IsADog`] and [`SupervisorError::Overrides`], as
    ///   [`Self::write_sheep_field`] raises them.
    pub(super) fn handle_reset_sheep_field(
        &mut self,
        name: &str,
        key: &str,
    ) -> Result<Option<FieldSet>, SupervisorError> {
        refuse_unowned_key(key)?;
        self.apply_sheep_field(name, key, FieldSource::Reset)
    }

    /// Records `key` on `name` as an operator override, applies what can
    /// reach the running process, and parks the rest for its next spawn.
    ///
    /// `Ok(None)` when no sheep has that name.
    ///
    /// # Why this is not `ApplyConfig`
    ///
    /// One [`DeclaredApp`] declaring one key, at [`ResetDepth::File`],
    /// moves exactly this one field and nothing else, and then
    /// [`merge_declared`] spends the override for it. That reasoning does
    /// not hold here: a key put back to the template is not a key an
    /// operator is still holding a value for, but a pane's value is the
    /// operator's, and the sheep still differs from its file. Routed that
    /// way, an edit would drop out of [`ProcessEntry::overridden`], so the
    /// `*` would never render. This writes the override directly instead
    /// of pretending to be a template.
    ///
    /// # Ordering
    ///
    /// Validate, then write the store, then apply. Every refusal below is
    /// raised before [`Self::mutate_override`], so an operator whose value
    /// this build will not take is left with the config they already had
    /// rather than a store that disagrees with the flock, the same rule
    /// [`Self::handle_set_sheep_env`] states and its own test pins.
    ///
    /// # Which fields reach a running process
    ///
    /// [`apply_group`]'s table, exactly as [`Self::apply_one`] reads it. A
    /// [`ApplyGroup::Live`] field goes onto the stored spec and is in force
    /// at the daemon's next decision; a [`ApplyGroup::NextSpawn`] field
    /// goes onto the stored spec too but is not in force until a spawn
    /// reads it, so it reports as pending, except `autostart`, which
    /// `restorable()` reads at muster rather than at a spawn and so is in
    /// force the moment it lands, the same carve-out `apply_one` makes. A
    /// [`ApplyGroup::NeedsRespawn`] field only parks.
    ///
    /// # `warning`, the one field this can answer besides `pending`
    ///
    /// `cwd`, `script`, `out_file` and `err_file` get a filesystem check
    /// nothing before this ran anywhere: `normalize` cannot see the
    /// filesystem, and a spawn is the daemon's own first look. A problem
    /// here never refuses the write; it names what the next respawn will
    /// otherwise fail on with a bare OS error. See [`FieldSet::warning`].
    ///
    /// # Errors
    ///
    /// - [`SupervisorError::IsADog`] - the name is a dog's. Raised before
    ///   the store is read, so nothing was written.
    /// - [`SupervisorError::InvalidField`] - `AppConfig` has no such key,
    ///   the value will not deserialize into it, or `normalize` refuses
    ///   the result. Nothing was written.
    /// - [`SupervisorError::Overrides`] - the override store could not be
    ///   read or written. Nothing was parked.
    pub(super) fn write_sheep_field(
        &mut self,
        name: &str,
        key: &str,
        value: &serde_json::Value,
    ) -> Result<Option<FieldSet>, SupervisorError> {
        self.apply_sheep_field(name, key, FieldSource::Set(value))
    }

    /// [`Self::write_sheep_field`] and [`Self::handle_reset_sheep_field`]:
    /// the one path that validates a field's value, writes the override
    /// store, and applies or parks the result. `source` is the only
    /// difference between the two, which is why they cannot drift.
    fn apply_sheep_field(
        &mut self,
        name: &str,
        key: &str,
        source: FieldSource<'_>,
    ) -> Result<Option<FieldSet>, SupervisorError> {
        let Some(id) = self.representative_id(name) else {
            return Ok(None);
        };
        // Before the store is read, for [`Self::ensure_not_dog`]'s reason:
        // this door reaches `script` and `args` directly.
        self.ensure_not_dog(name, id)?;
        let value = match source {
            FieldSource::Set(value) => value.clone(),
            FieldSource::Reset => self.template_value(name, key)?,
        };
        let value = &value;
        let Some(slot) = self.sheep.get(&id) else {
            return Ok(None);
        };
        // `running` is what the child was spawned from; `intended` is what
        // the app is meant to be, which is an earlier edit's parked config
        // when there is one. Building on `running` would drop that edit,
        // which is `apply_one`'s own reason for the same pair.
        let running = slot.entry.spec.config().clone();
        let intended = slot
            .entry
            .pending
            .as_ref()
            .map_or_else(|| running.clone(), |parked| parked.config().clone());

        let Ok(serde_json::Value::Object(mut object)) = serde_json::to_value(&intended) else {
            return Err(SupervisorError::InvalidField(
                "an app config must serialize as an object".to_string(),
            ));
        };
        // Checked rather than inserted blind. `AppConfig` would take an
        // unknown key without complaint or ignore it outright, either way
        // reporting a write that changed nothing, and a pane's key comes
        // off a schema this daemon may not share a version with.
        if !object.contains_key(key) {
            return Err(SupervisorError::InvalidField(format!(
                "no config field named {key}"
            )));
        }
        let before = object.insert(key.to_string(), value.clone());
        let edited: AppConfig = serde_json::from_value(serde_json::Value::Object(object))
            .map_err(|err| SupervisorError::InvalidField(format!("{key}: {err}")))?;
        let merged = normalize(edited)
            .map_err(|err| SupervisorError::InvalidField(format!("{key}: {err}")))?;

        // Advisory, never a second refusal: `normalize` cannot see the
        // filesystem (`normalize_with_home` says why). `cwd` and `script`
        // share one `preflight` since each resolves against the other. Each
        // arm builds its own spec so every other key skips `describe`.
        let warning = match key {
            "cwd" | "script" => {
                let view = self.secret_view(&merged);
                let spec = describe(&merged, 0, &self.paths, None, &view);
                spec.cwd.as_deref().and_then(cwd_advisory).or_else(|| {
                    match self.runner.preflight(&spec) {
                        Preflight::Impossible(reason) | Preflight::Doubtful(reason) => Some(reason),
                        Preflight::Unknown => None,
                    }
                })
            }
            "out_file" | "err_file" => {
                let view = self.secret_view(&merged);
                let spec = describe(&merged, 0, &self.paths, None, &view);
                log_path_advisory(if key == "out_file" {
                    &spec.out_file
                } else {
                    &spec.err_file
                })
            }
            _ => None,
        };

        // The one field that moved, if it moved at all. A value identical
        // to what is already intended still records the override (the
        // operator has spoken for the key, which is the whole point of
        // this door), but nothing needs applying or parking for it.
        let group = apply_group(key);
        let reaches = matches!(group, ApplyGroup::Live | ApplyGroup::NextSpawn);
        let reaching: Vec<String> = if reaches {
            vec![key.to_string()]
        } else {
            Vec::new()
        };
        // A subset of a valid config can still fail to normalize, because
        // `normalize` checks fields against each other: `watch` needs a
        // `cwd`, and a `cwd` left behind as `NeedsRespawn` takes the watch
        // down with it. `apply_one` treats that as "this app needs a
        // restart" rather than as an invalid request, and so does this.
        let next_spec = reached_spec(&running, merged.config(), &reaching, running.instances).ok();
        let park_all = next_spec.is_none();

        let overridden = self.mutate_override(name, |record| {
            match source {
                // The value the key held before this write is the one a
                // reset returns to, unless the operator already holds the
                // key and the record remembers an older one.
                FieldSource::Set(_) => {
                    if !record.fields.contains_key(key)
                        && let Some(before) = before
                    {
                        record.template.insert(key.to_string(), before);
                    }
                    record.fields.insert(key.to_string(), value.clone());
                }
                FieldSource::Reset => {
                    record.fields.remove(key);
                    record.template.remove(key);
                }
            }
            Ok(())
        })?;

        // Parked whenever the field cannot reach a running child, and also
        // whenever an earlier edit already left a config parked: that
        // config predates this one, and promoting it later would put this
        // field back. `apply_one` recomputes it on the same condition.
        let parked_wanted = park_all
            || !reaches
            || self.ids_of_name(name).iter().any(|id| {
                self.sheep
                    .get(id)
                    .is_some_and(|s| s.entry.pending.is_some())
            });
        let parked = parked_wanted.then(|| merged.clone());

        // Every slot of the name, and `ids_of_name` re-read for the reason
        // `handle_set_sheep_env` gives.
        for id in self.ids_of_name(name) {
            let Some(slot) = self.sheep.get_mut(&id) else {
                continue;
            };
            // Against this slot's own spec before it is overwritten, and
            // `|=`, for the reasons `apply_one` gives at the same line.
            if let Some(parked) = &parked {
                let spawned = slot.entry.spec.config();
                slot.entry.pending_reidentifies |=
                    spawned.user != parked.config().user || spawned.group != parked.config().group;
            }
            if let Some(next_spec) = next_spec.clone() {
                slot.entry.spec = next_spec;
            }
            if let Some(parked) = parked.clone() {
                slot.entry.pending = Some(parked);
            }
            slot.entry.overridden.clone_from(&overridden);
        }

        // A Live field the extras engine reads is re-armed now rather than
        // at the next spawn, the same line `apply_one` runs for the same
        // set of fields.
        if !park_all && group == ApplyGroup::Live && EXTRAS_FIELDS.contains(&key) {
            self.rearm_name(name);
        }

        // `reaches_running` owns the `autostart`/`depends_on` carve-out now,
        // so the pane's prediction and this answer cannot drift.
        let in_force = !park_all && reaches_running(key);
        Ok(Some(FieldSet {
            app: parked.unwrap_or_else(|| next_spec.unwrap_or(merged)),
            value: value.clone(),
            pending: !in_force,
            warning,
        }))
    }

    /// The value a reset puts `key` back to, from `name`'s override record.
    ///
    /// # Errors
    ///
    /// - [`SupervisorError::InvalidField`] - the operator holds no override of
    ///   `key`, so there is nothing to drop and a no-op would read as success.
    /// - [`SupervisorError::Overrides`] - the store could not be read.
    fn template_value(&self, name: &str, key: &str) -> Result<serde_json::Value, SupervisorError> {
        let record = overrides::get(&self.paths.overrides, name)
            .map_err(|err| SupervisorError::Overrides(err.to_string()))?
            .unwrap_or_default();
        if !record.fields.contains_key(key) {
            return Err(SupervisorError::InvalidField(format!(
                "{key} has no override to drop: it already holds the Flockfile's value"
            )));
        }
        if let Some(template) = record.template.get(key) {
            return Ok(template.clone());
        }
        let defaults = serde_json::to_value(AppConfig::default())
            .map_err(|err| SupervisorError::InvalidField(format!("{key}: {err}")))?;
        defaults
            .get(key)
            .cloned()
            .ok_or_else(|| SupervisorError::InvalidField(format!("no config field named {key}")))
    }
}

/// Where [`Actor::apply_sheep_field`] gets the value it applies.
#[derive(Clone, Copy)]
enum FieldSource<'a> {
    /// The operator's value, recorded as an override.
    Set(&'a serde_json::Value),
    /// The value the key held before the operator spoke for it, with the
    /// override dropped.
    Reset,
}

/// The refusal for the keys `SetSheepField` and `ResetSheepField` leave to
/// another request.
///
/// A pane is never sent a whole `env` or `dogs` map, and a wholesale write of
/// either would wipe every env key, or every other dog's table, but the one
/// being set. The Structural fields are identity and flock shape:
/// `handle_scale` owns the count.
///
/// # Errors
///
/// [`SupervisorError::InvalidField`] - `env`, `dogs`, or a Structural key.
fn refuse_unowned_key(key: &str) -> Result<(), SupervisorError> {
    let owner = match key {
        "env" => Some("env is set one key at a time; use `SetSheepEnv`"),
        "dogs" => Some("dogs is set one dog's table at a time; use `SetSheepDogSettings`"),
        _ => None,
    };
    if let Some(refusal) = owner {
        return Err(SupervisorError::InvalidField(refusal.to_string()));
    }
    if apply_group(key) == ApplyGroup::Structural {
        return Err(SupervisorError::InvalidField(format!(
            "{key} is not a config write; `shep stock` moves an instance count, and a \
             name change is a different sheep"
        )));
    }
    Ok(())
}