@agentsignalnet/claude-plugin 0.2.75 → 0.2.77

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "agentsignal",
3
3
  "displayName": "AgentSignal",
4
- "version": "0.2.75",
4
+ "version": "0.2.77",
5
5
  "description": "Page a human from inside Claude Code, or become an addressable agent that other agents can reach.",
6
6
  "author": {
7
7
  "name": "Data Group AI",
package/.mcp.json CHANGED
@@ -2,7 +2,7 @@
2
2
  "mcpServers": {
3
3
  "agentsignal": {
4
4
  "command": "npx",
5
- "args": ["-y", "@agentsignalnet/mcp@0.2.54"],
5
+ "args": ["-y", "@agentsignalnet/mcp@0.2.55"],
6
6
  "env": {
7
7
  "AGENTSIGNAL_API_KEY": "${user_config.api_key}",
8
8
  "AGENTSIGNAL_JOIN_TOKEN": "${user_config.join_token}",
package/commands/work.md CHANGED
@@ -18,6 +18,10 @@ not merely misfiled. It was sent to the wrong company.
18
18
  So settle it before the loop starts, not on the first message that needs it:
19
19
 
20
20
  1. Call `my_channels`. One channel is the answer, and no question is needed.
21
+ When the channels span more than one company it says so on every line and
22
+ again at the end — that listing is the check, and it exists because the rule
23
+ was unenforceable without it: until the API sent the account, an agent asked
24
+ which company it was working in had nothing to answer with.
21
25
  2. Several, and the request names one -- by channel, by company, or plainly
22
26
  enough from the work itself -- use that, and SAY which you chose, so a wrong
23
27
  guess is caught in the first line rather than three messages in.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@agentsignalnet/claude-plugin",
3
- "version": "0.2.75",
3
+ "version": "0.2.77",
4
4
  "publishConfig": {
5
5
  "access": "public"
6
6
  },
@@ -35,6 +35,7 @@ import { randomUUID } from 'node:crypto';
35
35
  import { readFileSync } from 'node:fs';
36
36
  import { homedir } from 'node:os';
37
37
  import { join } from 'node:path';
38
+ import { fileURLToPath } from 'node:url';
38
39
  import { mkdirSync, writeFileSync, readdirSync, statSync, unlinkSync } from 'node:fs';
39
40
  import { randomUUID as uuid } from 'node:crypto';
40
41
  import {
@@ -160,6 +161,77 @@ const token = randomUUID();
160
161
  /** Where the token lives after the first visit. Namespaced: localhost is shared. */
161
162
  const COOKIE = 'agentsignal_viewer';
162
163
 
164
+ /**
165
+ * THE LOCK, so a newer build replaces the one already on this port.
166
+ *
167
+ * A dashboard is a long-lived process nobody restarts on purpose. Update the
168
+ * plugin and the running one keeps serving the old code -- indefinitely, and
169
+ * silently, because it works. Worse, the port-in-use message added earlier says
170
+ * "that is usually a dashboard already running, find the link it printed",
171
+ * which is exactly the wrong advice after an update: the running one is the
172
+ * stale one, and finding its link is how you keep using it.
173
+ *
174
+ * The watcher solved this for itself long ago and this is the same machinery:
175
+ * compare build times, take over when newer, stand down when not.
176
+ *
177
+ * KEYED ON THE PORT, which is the difference from the watcher. One watcher per
178
+ * machine is right; one dashboard per machine is NOT -- a second company needs
179
+ * a second dashboard, and the one-company rule says so in as many words. Two on
180
+ * different ports are two scopes, deliberately. Two on the SAME port are an
181
+ * accident, and only that case is settled here.
182
+ *
183
+ * PORT=0 takes no lock at all. It means "any free port", so it collides with
184
+ * nothing and supersedes nothing; the tests run that way, and a test that
185
+ * killed the developer's dashboard would be a memorable way to learn this.
186
+ */
187
+ const lockRoot = process.env.AGENTSIGNAL_STATE_DIR || join(homedir(), '.agentsignal');
188
+ const lockPath = port ? join(lockRoot, `dashboard-${port}.pid`) : null;
189
+ const lockMetaPath = port ? join(lockRoot, `dashboard-${port}.meta.json`) : null;
190
+
191
+ /** When THIS build was written, which is what decides who is newer. */
192
+ function buildTime() {
193
+ try {
194
+ return statSync(fileURLToPath(import.meta.url)).mtimeMs;
195
+ } catch {
196
+ return 0;
197
+ }
198
+ }
199
+
200
+ /** The live dashboard holding this port, if there is one. */
201
+ function holder() {
202
+ if (!lockPath) return null;
203
+ let pid;
204
+ try {
205
+ pid = Number(readFileSync(lockPath, 'utf8').trim());
206
+ if (!Number.isInteger(pid) || pid <= 0 || pid === process.pid) return null;
207
+ // ESRCH: a pidfile left by a machine that lost power looks exactly like a
208
+ // live one until you ask.
209
+ process.kill(pid, 0);
210
+ } catch {
211
+ return null;
212
+ }
213
+ try {
214
+ const meta = JSON.parse(readFileSync(lockMetaPath, 'utf8'));
215
+ if (meta?.pid === pid) return { pid, script: meta.script ?? null, mtime: meta.mtime ?? 0 };
216
+ } catch {
217
+ /* absent, unreadable, or about somebody else */
218
+ }
219
+ return { pid, script: null, mtime: 0 };
220
+ }
221
+
222
+ async function goneWithin(pid, ms) {
223
+ const deadline = Date.now() + ms;
224
+ while (Date.now() < deadline) {
225
+ try {
226
+ process.kill(pid, 0);
227
+ } catch {
228
+ return true;
229
+ }
230
+ await new Promise((r) => setTimeout(r, 100));
231
+ }
232
+ return false;
233
+ }
234
+
163
235
  /**
164
236
  * RE-READING A PENDING ROW, briefly, because delivery state changes after the
165
237
  * row is cached and `since` guarantees it is never looked at again.
@@ -743,6 +815,25 @@ const PAGE = `<!doctype html>
743
815
  .answer .who { color: var(--dim); font-weight: 500; }
744
816
  .answer .time { color: var(--dim); font-size: 12px; margin-left: auto; }
745
817
 
818
+ .pick { padding: 4px 2px; }
819
+ .pick-why { margin: 0 0 8px; font-size: 12px; color: var(--dim); line-height: 1.5; }
820
+ .pick-one {
821
+ display: block; width: 100%; text-align: left; margin: 0 0 6px;
822
+ padding: 8px 10px; font: inherit; font-weight: 600; cursor: pointer;
823
+ border: 1px solid var(--line); border-radius: 8px;
824
+ background: var(--surface); color: var(--fg);
825
+ }
826
+ .pick-one:hover { border-color: var(--accent); }
827
+ /* Present, and plainly not a control. No hover, no pointer, no accent: the
828
+ point is that it exists somewhere else, not that it can be opened here. */
829
+ .elsewhere { margin-top: 14px; padding-top: 10px; border-top: 1px solid var(--line); }
830
+ .elsewhere-title, .elsewhere-why {
831
+ margin: 0 0 6px; font-size: 11px; letter-spacing: .04em; text-transform: uppercase;
832
+ color: var(--dim);
833
+ }
834
+ .elsewhere-why { text-transform: none; letter-spacing: 0; font-size: 12px; margin-top: 8px; }
835
+ .elsewhere-chan { margin: 0 0 2px; padding-left: 2px; font-size: 13px; color: var(--dim); }
836
+
746
837
  .chan { margin-bottom: 4px; }
747
838
  .chan-head { display: flex; align-items: center; gap: 2px; }
748
839
  .twist {
@@ -1262,6 +1353,9 @@ const PAGE = `<!doctype html>
1262
1353
 
1263
1354
  /** Every channel the server can open, from the poll. */
1264
1355
  let CHANNELS = [];
1356
+ /* The company this dashboard is for, and the ones it merely knows about. */
1357
+ let BOUND = null;
1358
+ let COMPANIES = [];
1265
1359
  /** Which of them are expanded in the rail. */
1266
1360
  const OPEN = new Set();
1267
1361
  /** The rendered agent tree per channel, so reopening one costs nothing. */
@@ -1580,17 +1674,70 @@ const PAGE = `<!doctype html>
1580
1674
  rail really is a flat list of channels and "Companies" would name a level
1581
1675
  that is not on screen.
1582
1676
  */
1583
- document.getElementById('rail-title').textContent = sectioned ? 'Companies' : 'Channels';
1584
-
1585
- nav.innerHTML = groups
1586
- .map((g) =>
1587
- sectioned
1588
- ? '<div class="company"><p class="company-name">' +
1589
- esc(g.company || 'Unnamed company') +
1590
- '</p>' + rows(g.channels) + '</div>'
1591
- : rows(g.channels),
1592
- )
1593
- .join('');
1677
+ /*
1678
+ THE TITLE IS THE SCOPE. A dashboard is for one company, so the company
1679
+ belongs at the top as its name rather than repeated as a section label
1680
+ above every row. When it is not yet known -- no poll has answered -- the
1681
+ rail says what it is showing instead of asserting a company it cannot
1682
+ name.
1683
+ */
1684
+ const boundName = (COMPANIES.find((k) => k.account === BOUND) || {}).company;
1685
+ document.getElementById('rail-title').textContent = boundName || 'Channels';
1686
+
1687
+ /*
1688
+ A CHOICE, when there is genuinely one to make.
1689
+
1690
+ Binding happens by itself when this machine holds keys to one company,
1691
+ which is the ordinary case and needs no question. With two, the question
1692
+ cannot be skipped: picking for somebody would decide whose rules the
1693
+ session works under, which is the decision this rule exists to make
1694
+ deliberate.
1695
+ */
1696
+ if (!BOUND && COMPANIES.length > 1) {
1697
+ nav.innerHTML =
1698
+ '<div class="pick"><p class="pick-why">This dashboard is for one company. ' +
1699
+ 'Which one is this session working in?</p>' +
1700
+ COMPANIES.map(
1701
+ (k) =>
1702
+ '<button type="button" class="pick-one" data-account="' + esc(k.account) + '">' +
1703
+ esc(k.company || 'Unnamed company') + '</button>',
1704
+ ).join('') +
1705
+ '<p class="pick-why">The others stay listed once you choose, and open in their own ' +
1706
+ 'dashboard rather than this one.</p></div>';
1707
+ return;
1708
+ }
1709
+
1710
+ const mine = groups.filter((g) => !g.at || g.at === BOUND);
1711
+ const others = groups.filter((g) => g.at && g.at !== BOUND);
1712
+
1713
+ nav.innerHTML =
1714
+ mine.map((g) => rows(g.channels)).join('') +
1715
+ /*
1716
+ NAMED, NOT HIDDEN. A channel that vanishes is a channel somebody hunts
1717
+ for; one that says which company it belongs to answers the question its
1718
+ absence would raise. Inert on purpose -- opening it here is what a
1719
+ dashboard for one company must not do.
1720
+ */
1721
+ (others.length
1722
+ ? '<div class="elsewhere"><p class="elsewhere-title">Other companies</p>' +
1723
+ others
1724
+ .map(
1725
+ (g) =>
1726
+ '<div class="company"><p class="company-name">' +
1727
+ esc(g.company || 'Unnamed company') +
1728
+ '</p>' +
1729
+ g.channels
1730
+ .map(
1731
+ (c) =>
1732
+ '<p class="elsewhere-chan">' + esc(c.name || c.ref || 'channel') + '</p>',
1733
+ )
1734
+ .join('') +
1735
+ '</div>',
1736
+ )
1737
+ .join('') +
1738
+ '<p class="elsewhere-why">A different company, so a different dashboard. Start one ' +
1739
+ 'with that key, on another port if this one is busy.</p></div>'
1740
+ : '');
1594
1741
 
1595
1742
  markNav();
1596
1743
  }
@@ -1621,9 +1768,11 @@ const PAGE = `<!doctype html>
1621
1768
  }
1622
1769
 
1623
1770
  /** Keep the rail in step with what the poll says exists. */
1624
- function renderChannels(list) {
1771
+ function renderChannels(list, bound, companies) {
1625
1772
  if (!list) return;
1626
1773
  CHANNELS = list;
1774
+ BOUND = bound ?? null;
1775
+ COMPANIES = companies ?? [];
1627
1776
  const active = list.find((c) => c.active);
1628
1777
  // The channel being read starts open, because its members are the ones
1629
1778
  // the log is about. The rest stay shut until asked for.
@@ -1779,7 +1928,7 @@ const PAGE = `<!doctype html>
1779
1928
  // the channel you cannot read is the one where you most need the list of
1780
1929
  // the others. Returning first left the page knowing about two channels and
1781
1930
  // showing neither.
1782
- renderChannels(data.channels);
1931
+ renderChannels(data.channels, data.bound, data.companies);
1783
1932
 
1784
1933
  if (data.error) {
1785
1934
  document.getElementById('log').className = 'empty';
@@ -2529,6 +2678,22 @@ const PAGE = `<!doctype html>
2529
2678
  document.getElementById('who-nav').addEventListener('click', (event) => {
2530
2679
  // The twisty opens and closes without going anywhere. Checked first
2531
2680
  // because it sits inside the same row as the link beside it.
2681
+ const pick = event.target.closest('.pick-one');
2682
+ if (pick) {
2683
+ event.preventDefault();
2684
+ post('/bind', { account: pick.dataset.account }).then((r) => {
2685
+ if (r.error) {
2686
+ window.alert(r.error);
2687
+ return;
2688
+ }
2689
+ // Re-poll rather than guess: the server decides the scope, and the
2690
+ // rail should redraw from what it says rather than from what was
2691
+ // clicked.
2692
+ tick();
2693
+ });
2694
+ return;
2695
+ }
2696
+
2532
2697
  const twist = event.target.closest('.twist');
2533
2698
  if (twist) {
2534
2699
  event.preventDefault();
@@ -2583,9 +2748,58 @@ const PAGE = `<!doctype html>
2583
2748
  * this machine currently is. An unknown ref falls back rather than erroring:
2584
2749
  * a stale bookmark should show something, not a stack trace.
2585
2750
  */
2751
+ /**
2752
+ * THE COMPANY THIS DASHBOARD IS FOR. One, for the whole run.
2753
+ *
2754
+ * A machine accumulates keys -- from the environment, from MCP config, from the
2755
+ * identity it holds now and from the ones it used to hold -- and nothing said
2756
+ * those had to belong to the same company. So one window could show two
2757
+ * companies' conversations side by side: two rule sets, two billing accounts,
2758
+ * two sets of people, one credential-holder straddling them. An agent working
2759
+ * out of that window has no single answer to "whose rules apply", and neither
2760
+ * does the person reading it.
2761
+ *
2762
+ * So the scope is chosen once and named at the top. Other companies are not
2763
+ * hidden -- knowing they exist is useful, and a channel that vanishes is a
2764
+ * channel somebody hunts for -- they are listed, inert, and say which company
2765
+ * they belong to and that they need their own dashboard.
2766
+ *
2767
+ * Null until chosen. It cannot be settled at startup: a channel's ref comes out
2768
+ * of its key, but the company comes from the API, so the question can only be
2769
+ * asked once something has answered.
2770
+ */
2771
+ let boundTo = null;
2772
+
2773
+ /** The name of a company by account id, for saying which one this is. */
2774
+ function nameOf(account) {
2775
+ if (!account) return null;
2776
+ return channels.find((c) => c.account === account)?.company ?? null;
2777
+ }
2778
+
2779
+ /** Companies this machine holds a key for, once the API has said. */
2780
+ function companiesKnown() {
2781
+ const byId = new Map();
2782
+ for (const c of channels) {
2783
+ if (!c.account) continue;
2784
+ if (!byId.has(c.account)) byId.set(c.account, { account: c.account, company: c.company ?? null });
2785
+ }
2786
+ return [...byId.values()];
2787
+ }
2788
+
2789
+ /** True when this channel belongs to the company this dashboard is for. */
2790
+ function inScope(c) {
2791
+ if (!boundTo) return true;
2792
+ // An account not yet known is not yet out of scope. It resolves on the poll
2793
+ // that names it, and refusing before then would hide a channel for being
2794
+ // slow rather than for being elsewhere.
2795
+ return !c.account || c.account === boundTo;
2796
+ }
2797
+
2586
2798
  function channelFor(ref) {
2587
- if (!ref) return channels[0];
2588
- return channels.find((c) => c.ref === ref) ?? channels[0];
2799
+ if (!ref) return channels.find(inScope) ?? channels[0];
2800
+ const found = channels.find((c) => c.ref === ref);
2801
+ if (found) return found;
2802
+ return channels.find(inScope) ?? channels[0];
2589
2803
  }
2590
2804
 
2591
2805
  /** One upstream call, one place that turns a non-2xx into something readable. */
@@ -3609,6 +3823,49 @@ const server = createServer(async (req, res) => {
3609
3823
  return;
3610
3824
  }
3611
3825
 
3826
+ /*
3827
+ CHOOSING THE COMPANY, once per run.
3828
+
3829
+ A POST rather than a query parameter: this changes what the whole process is
3830
+ for, and a link that silently rebinds the scope is the thing being prevented
3831
+ -- somebody following it would be reading another company under a name they
3832
+ chose earlier.
3833
+ */
3834
+ if (url.pathname === '/bind' && req.method === 'POST') {
3835
+ let payload;
3836
+ try {
3837
+ payload = await readJson(req);
3838
+ } catch {
3839
+ res.writeHead(400, { 'Content-Type': 'application/json' });
3840
+ res.end(JSON.stringify({ error: 'Unreadable request.' }));
3841
+ return;
3842
+ }
3843
+ const known = companiesKnown();
3844
+ const picked = known.find((k) => k.account === payload.account);
3845
+ if (!picked) {
3846
+ res.writeHead(400, { 'Content-Type': 'application/json' });
3847
+ res.end(JSON.stringify({ error: 'No key on this machine belongs to that company.' }));
3848
+ return;
3849
+ }
3850
+ // Once. Rebinding mid-run would leave the page showing rows read under the
3851
+ // previous scope, which is the mixture this exists to stop.
3852
+ if (boundTo && boundTo !== picked.account) {
3853
+ res.writeHead(409, { 'Content-Type': 'application/json' });
3854
+ res.end(
3855
+ JSON.stringify({
3856
+ error:
3857
+ `This dashboard is already for ${nameOf(boundTo) ?? 'a company'}. Start another one ` +
3858
+ 'for a different company rather than switching this one.',
3859
+ }),
3860
+ );
3861
+ return;
3862
+ }
3863
+ boundTo = picked.account;
3864
+ res.writeHead(200, { 'Content-Type': 'application/json' });
3865
+ res.end(JSON.stringify({ ok: true, bound: boundTo, company: picked.company }));
3866
+ return;
3867
+ }
3868
+
3612
3869
  if (url.pathname === '/messages') {
3613
3870
  /**
3614
3871
  * ASK FOR WHAT IS NEW, not for the last hundred every two seconds.
@@ -3634,6 +3891,81 @@ const server = createServer(async (req, res) => {
3634
3891
  const want = url.searchParams.get('channel');
3635
3892
  const on = channelFor(want);
3636
3893
 
3894
+ /*
3895
+ ONE COMPANY IS NOT A QUESTION. Binding automatically when only one is
3896
+ known keeps the ordinary case free of a chooser that offers a single
3897
+ answer -- and the ordinary case is one company, because most machines hold
3898
+ keys to one.
3899
+ */
3900
+ const known = companiesKnown();
3901
+ if (!boundTo && known.length === 1) boundTo = known[0].account;
3902
+
3903
+ /*
3904
+ NOTHING IS READ WHILE THE QUESTION IS OPEN.
3905
+
3906
+ The first poll has to happen -- a company is only known once the API says
3907
+ so -- but once two are known and none is chosen, reading on is showing one
3908
+ company's conversation behind a question about which company this is. That
3909
+ is the mixing this rule exists to prevent, arriving a second before the
3910
+ answer. It also costs money: a log read that returns rows is billed, and
3911
+ billing one company to decorate a chooser is the wrong account either way.
3912
+ */
3913
+ if (!boundTo && known.length > 1) {
3914
+ res.writeHead(200, { 'Content-Type': 'application/json' });
3915
+ res.end(
3916
+ JSON.stringify({
3917
+ ok: true,
3918
+ messages: [],
3919
+ channels: channels.map((c) => ({
3920
+ ref: c.ref,
3921
+ name: c.name ?? c.via,
3922
+ via: c.via,
3923
+ account: c.account ?? null,
3924
+ company: c.company ?? null,
3925
+ active: false,
3926
+ elsewhere: false,
3927
+ })),
3928
+ bound: null,
3929
+ companies: known,
3930
+ fetched: 0,
3931
+ }),
3932
+ );
3933
+ return;
3934
+ }
3935
+
3936
+ /*
3937
+ Reading a channel belonging to another company is refused HERE rather than
3938
+ being quietly redirected, because a redirect would show a different
3939
+ conversation under the name that was asked for -- which is the failure
3940
+ this whole rule exists to prevent.
3941
+ */
3942
+ if (want && on && on.ref === want && !inScope(on)) {
3943
+ res.writeHead(200, { 'Content-Type': 'application/json' });
3944
+ res.end(
3945
+ JSON.stringify({
3946
+ ok: true,
3947
+ error:
3948
+ `That channel belongs to ${on.company ?? 'another company'}, and this dashboard is ` +
3949
+ `for ${nameOf(boundTo) ?? 'one company'}. Open it in its own dashboard: ` +
3950
+ 'stop this one and start another with that company\'s key, or run a second on ' +
3951
+ 'another port with PORT.',
3952
+ channels: channels.map((c) => ({
3953
+ ref: c.ref,
3954
+ name: c.name ?? c.via,
3955
+ via: c.via,
3956
+ account: c.account ?? null,
3957
+ company: c.company ?? null,
3958
+ active: false,
3959
+ elsewhere: !inScope(c),
3960
+ })),
3961
+ bound: boundTo,
3962
+ companies: known,
3963
+ messages: [],
3964
+ }),
3965
+ );
3966
+ return;
3967
+ }
3968
+
3637
3969
  // Per channel, because history is per channel: sharing one `since` across
3638
3970
  // two would make each ask for messages newer than the other's newest and
3639
3971
  // leave a hole in whichever is quieter.
@@ -3764,8 +4096,21 @@ const server = createServer(async (req, res) => {
3764
4096
  account: c.account ?? null,
3765
4097
  company: c.company ?? null,
3766
4098
  active: c === on,
4099
+ // Listed either way, and marked. A channel that disappears is one
4100
+ // somebody hunts for; a channel that says "different company, needs its
4101
+ // own dashboard" answers the question it raises.
4102
+ elsewhere: !inScope(c),
3767
4103
  }));
3768
4104
 
4105
+ /*
4106
+ The scope, and the choice when there is one to make. Sent every poll
4107
+ rather than once, because the companies are learned as the polls answer:
4108
+ a page told "one company" at boot must be told "two, pick" when the
4109
+ second one names itself a second later.
4110
+ */
4111
+ body.bound = boundTo;
4112
+ body.companies = companiesKnown();
4113
+
3769
4114
  const agent = url.searchParams.get('agent');
3770
4115
 
3771
4116
  // Filtered here rather than in the page, so the browser never holds
@@ -3915,12 +4260,113 @@ server.on('error', (error) => {
3915
4260
  process.exit(1);
3916
4261
  });
3917
4262
 
4263
+ /**
4264
+ * Take the port from an older build, or stand down to a newer one.
4265
+ *
4266
+ * Runs before listen, so nothing is half-bound either way, and the answer is
4267
+ * decided on BUILD TIME rather than start time: an old process started five
4268
+ * minutes ago is still old, and a new one started an hour ago is still new.
4269
+ * Start time would make "whoever restarted last wins", which is how a stale
4270
+ * build reclaims a port from the fix for it.
4271
+ */
4272
+ async function settlePort() {
4273
+ const running = holder();
4274
+ if (!running) return;
4275
+
4276
+ const mine = buildTime();
4277
+ if (!(mine > running.mtime)) {
4278
+ /*
4279
+ NOT OLDER, so leave it alone. It is already serving, and its link works;
4280
+ replacing it would kill a page somebody has open to hand them an
4281
+ identical one. This is the message the port-in-use path used to give and
4282
+ it is right HERE, where the running build is not stale.
4283
+ */
4284
+ console.error(`Port ${port} is already served by a dashboard of the same build or newer (pid ${running.pid}).`);
4285
+ console.error('Nothing to update, so it has been left alone — find the link it printed');
4286
+ console.error(`when it started, or stop it first. To run another alongside it: PORT=${port + 1} …`);
4287
+ process.exit(0);
4288
+ }
4289
+
4290
+ console.error(`superseding pid ${running.pid} (${running.script ?? 'an older dashboard'})`);
4291
+ try {
4292
+ // SIGTERM: it has a socket to close and pages to stop serving, and a
4293
+ // signal it could handle is worth sending politely first.
4294
+ process.kill(running.pid, 'SIGTERM');
4295
+ } catch {
4296
+ /* it went on its own between the check and the signal */
4297
+ }
4298
+
4299
+ if (!(await goneWithin(running.pid, 5000))) {
4300
+ // Two dashboards on one port cannot both bind, so carrying on would fail
4301
+ // at listen with a message about the port rather than about this.
4302
+ console.error(`pid ${running.pid} did not exit; leaving it alone rather than fighting for the port.`);
4303
+ process.exit(1);
4304
+ }
4305
+ }
4306
+
4307
+ /**
4308
+ * Whether the lock on disk is OURS.
4309
+ *
4310
+ * A process that stands down must not tidy up on its way out: the files it
4311
+ * would delete belong to the dashboard still serving, and removing them leaves
4312
+ * a live process with no lock — so the next start finds no holder, supersedes
4313
+ * nothing, and collides on the port instead.
4314
+ *
4315
+ * Found by the test rather than by reading: two on different ports, and the
4316
+ * first port's lock had disappeared while its process was still answering.
4317
+ */
4318
+ let holdsLock = false;
4319
+
4320
+ /** Written after the bind, so the file never names a process that failed to start. */
4321
+ function takeLock() {
4322
+ if (!lockPath) return;
4323
+ try {
4324
+ mkdirSync(lockRoot, { recursive: true });
4325
+ writeFileSync(
4326
+ lockMetaPath,
4327
+ JSON.stringify({ pid: process.pid, script: fileURLToPath(import.meta.url), mtime: buildTime(), port: bound }),
4328
+ { mode: 0o600 },
4329
+ );
4330
+ writeFileSync(lockPath, String(process.pid), { mode: 0o600 });
4331
+ holdsLock = true;
4332
+ } catch {
4333
+ /* an unwritable state directory is not a reason to refuse to serve */
4334
+ }
4335
+ }
4336
+
4337
+ /**
4338
+ * Put the lock down on the way out, so the next start reads an empty port
4339
+ * rather than asking the operating system about a pid that has been recycled.
4340
+ * Best effort: a SIGKILL leaves it behind, which `holder()` handles by asking
4341
+ * whether the pid is alive rather than trusting the file.
4342
+ */
4343
+ function dropLock() {
4344
+ if (!lockPath || !holdsLock) return;
4345
+ for (const path of [lockPath, lockMetaPath]) {
4346
+ try {
4347
+ unlinkSync(path);
4348
+ } catch {
4349
+ /* already gone */
4350
+ }
4351
+ }
4352
+ }
4353
+ process.on('exit', dropLock);
4354
+ for (const signal of ['SIGINT', 'SIGTERM']) {
4355
+ process.on(signal, () => {
4356
+ dropLock();
4357
+ process.exit(0);
4358
+ });
4359
+ }
4360
+
4361
+ await settlePort();
4362
+
3918
4363
  server.listen(port, '127.0.0.1', () => {
3919
4364
  // The port the OS actually gave us, not the one asked for. They differ
3920
4365
  // whenever PORT is 0 -- which is how anything automated starts a server
3921
4366
  // without picking a number and hoping -- and printing the request rather
3922
4367
  // than the result hands out a link to port 0, which connects to nothing.
3923
4368
  bound = server.address()?.port ?? port;
4369
+ takeLock();
3924
4370
  console.error(`Watching ${baseUrl} on http://127.0.0.1:${bound}/?t=${token}`);
3925
4371
  console.error('Loopback only, and the link carries a one-run token: it can now send and answer.');
3926
4372
  console.error('The key stays in this process; the page only ever talks to this server.');