computers: a second PC claiming a machine is a claim, not a handover

Treating "another PC is linked to this machine" as proof of replacement was
wrong. A PC imaged for machine 3010 carries that number from the bench, before
it has replaced anything, and several PCs sharing one machine number is a
normal state at this site: the part markers do it. Both PCs then reported on
their own schedules, each report moved the link and raised an alert, and the
pair traded the machine back and forth for as long as both were alive.

The PC holding a machine now keeps it while it is still alive. Alive means it
has reported within MACHINE_CLAIM_QUIET_HOURS and its asset is still In Use. A
challenger is recorded as a dormant link instead, which doubles as the marker
saying the claim has already been announced, so a PC sitting on a bench does
not alert on every collector cycle.

The handover still happens on its own once the old PC has been quiet for a day,
which is what a PC pulled off a machine does. Moving the old PC off In Use -
Retired, Inventory, In Repair - hands the machine over on the next report,
which gives IT a one-step way to force a swap the moment it happens rather than
waiting out the window. A day is long enough that a PC switched off overnight,
or one behind a network outage, never loses its bay to a spare.

Alerts for both cases are gated on a new computers_machinelink_alerts setting
and ship OFF. Several part markers legitimately share a machine number here, so
the alerts would fire on correct data. Links, warnings in the collector
response, and archived history are unaffected; only the sending is gated.

Also: the alert goes through send_alert rather than resolving recipients by
hand, which had missed the SMTP_ALERT_RECIPIENTS environment fallback, so a
site configuring SMTP by environment would have got the webhook and no email.
This commit is contained in:
cproudlock
2026-08-10 14:48:51 -04:00
parent 9512b0bdb3
commit 5108ba8aaa
3 changed files with 400 additions and 42 deletions

View File

@@ -55,10 +55,23 @@ ADR-007 and ADR-002.
that had been pulled out. The link is a `controls` relationship carrying a
`collector:machine` origin label, so a link made by hand is never touched.
Superseding a PC archives the old link rather than deleting it, keeping the
history of which PC ran a machine and when, and raises an alert by email and
webhook. The retired PC's status is deliberately left alone: the collector
cannot tell whether it was shelved, sent for repair or re-imaged for another
bay, so a person decides.
history of which PC ran a machine and when. The retired PC's status is
deliberately left alone: the collector cannot tell whether it was shelved,
sent for repair or re-imaged for another bay, so a person decides.
A second PC reporting a machine another PC already holds is treated as a
claim, not a handover. A PC imaged for a machine carries that number before
it ever reaches the floor, so the PC actually running the machine keeps the
link while it is still reporting and still In Use, and the challenger is
recorded as a dormant link. The handover completes on its own once the old PC
has been quiet for a day, or immediately when someone moves it off In Use.
Without this the two PCs traded the link back and forth on every collector
cycle.
Alerts for both cases go out by email and webhook, gated on a new
`computers_machinelink_alerts` setting that ships OFF: a site may legitimately
run several PCs on one machine number, and there the alerts fire on correct
data. The collector response warns either way.
- Plugin contract 0.16.0: `get_settings_defaults()` lets a plugin declare the
settings it owns (key, default, type, category, description, and whether an
unauthenticated caller may read it). See `docs/PLUGIN-HOOKS.md`.