@agentsignalnet/claude-plugin 0.2.99 → 0.2.101

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.99",
4
+ "version": "0.2.101",
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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@agentsignalnet/claude-plugin",
3
- "version": "0.2.99",
3
+ "version": "0.2.101",
4
4
  "publishConfig": {
5
5
  "access": "public"
6
6
  },
@@ -388,11 +388,49 @@ async function considerResponding(watched) {
388
388
  say(`responder answering ${message.delivery_id} (${config.mode}) from ${verdict.peer ?? 'unknown'}`);
389
389
 
390
390
  const child = spawnResponder(message, config, identity.dir);
391
+
392
+ /*
393
+ READ WHAT IT SAYS, for two reasons and the second is worse.
394
+
395
+ The ledger recorded `exit_code: 1` and nothing else, so five spawns on
396
+ this machine looked identical and none of them could be explained. They
397
+ were not the same: the first two died because --allowed-tools had eaten
398
+ the prompt, and the last three because the spawned session could not
399
+ authenticate. Same code, same silence, different faults -- and the
400
+ second was invisible until the first was fixed.
401
+
402
+ The worse reason: stdout and stderr were piped and never read. A pipe
403
+ has a finite buffer, so a session that printed more than about 64KB
404
+ would BLOCK on the write, forever. It holds the single-flight lock
405
+ while it does, which means one talkative session stops this machine
406
+ ever running a responder again. Draining is what prevents that; keeping
407
+ the tail is what makes it useful.
408
+
409
+ Bounded, because this ends up in a ledger that has to stay readable,
410
+ and the interesting part of a failure is at the end.
411
+ */
412
+ let tail = '';
413
+ const keep = (chunk) => {
414
+ tail = (tail + chunk).slice(-2000);
415
+ };
416
+ child.stdout?.on('data', keep);
417
+ child.stderr?.on('data', keep);
418
+
391
419
  child.on('exit', (code) => {
392
420
  releaseLock();
393
- recordResponder({ event: 'finished', at: Date.now(),
394
- delivery_id: message.delivery_id, exit_code: code });
395
- say(`responder finished ${message.delivery_id} with code ${code}`);
421
+ const why = tail.trim().split('\n').filter(Boolean).at(-1) ?? null;
422
+ recordResponder({
423
+ event: 'finished', at: Date.now(),
424
+ delivery_id: message.delivery_id, exit_code: code,
425
+ // Only when something went wrong. A successful answer has nothing to
426
+ // explain, and its output is the reply itself -- which belongs in
427
+ // the channel, not in a log on this machine.
428
+ ...(code === 0 ? {} : { why: why ? why.slice(0, 300) : null }),
429
+ });
430
+ say(
431
+ `responder finished ${message.delivery_id} with code ${code}` +
432
+ (code === 0 || !why ? '' : `: ${why.slice(0, 200)}`),
433
+ );
396
434
  });
397
435
 
398
436
  // One per pass. The lock enforces this anyway; returning makes it true
@@ -489,7 +527,42 @@ async function pollOne(identity) {
489
527
  // mid-poll cannot lose a message between them.
490
528
  const handled = new Set(readHandled(dir));
491
529
  const outstanding = spool.messages.filter((m) => !handled.has(m.delivery_id));
492
- if (outstanding.length !== spool.messages.length) {
530
+ const shrank = outstanding.length !== spool.messages.length;
531
+
532
+ /*
533
+ A MESSAGE WITH NO STAMP GETS ONE, rather than being refused forever.
534
+
535
+ `spooled_at` was added on 2026-08-20. Anything spooled before that has no
536
+ stamp, and `mayRespond` refuses an unstamped message because without one it
537
+ cannot tell whether the grace period has elapsed. That refusal is correct
538
+ and its consequence was not: the message can never become answerable, and
539
+ it never leaves either -- the spool only shrinks when a hook marks
540
+ something handled. Three of them were sitting on the machine this was
541
+ written on, refused 291 times each.
542
+
543
+ Stamping on first sight is the conservative repair. It does not claim to
544
+ know when the message arrived; it records when this daemon first saw it,
545
+ which is a lower bound on how long it has been waiting, and starts the
546
+ grace period from there. Written back to the spool, so a restart does not
547
+ reset it and a message cannot be held at arm's length forever by a daemon
548
+ that keeps starting.
549
+ */
550
+ const now = new Date().toISOString();
551
+ let stamped = 0;
552
+ for (const message of outstanding) {
553
+ if (!message.spooled_at) {
554
+ message.spooled_at = now;
555
+ stamped += 1;
556
+ }
557
+ }
558
+ if (stamped > 0) {
559
+ say(
560
+ `stamped ${stamped} message(s) that predate spooled_at; ` +
561
+ 'their grace period starts now',
562
+ );
563
+ }
564
+
565
+ if (shrank || stamped > 0) {
493
566
  spool.messages = outstanding;
494
567
  writeSpool(spoolFile, spool);
495
568
  }
@@ -876,7 +949,33 @@ const startupLockPath = join(lockRoot, 'starting.lock');
876
949
  const LONGEST_HOLD_MS = 10_000;
877
950
  const WAIT_STEP_MS = 100;
878
951
  const WAIT_ATTEMPTS = Math.ceil((LONGEST_HOLD_MS * 3) / WAIT_STEP_MS);
879
- const HELD_TOO_LONG_MS = LONGEST_HOLD_MS * 6;
952
+ /*
953
+ STALE MUST BE REACHED BEFORE THE WAITER GIVES UP, or it is not a timeout a
954
+ waiter can ever act on.
955
+
956
+ This was `* 6`, sixty seconds, against a wait budget of thirty. A waiter that
957
+ arrives to find a FRESH lock sleeps 300 times at 100ms and gives up at thirty
958
+ seconds -- it can never observe a lock reach sixty, so for that waiter the
959
+ threshold did not exist. It fired only when the lock was already old on
960
+ arrival, which is the case that was never the problem.
961
+
962
+ The case that is: a holder wedges at t=0, a waiter arrives at t=1s, waits its
963
+ full budget, and proceeds WITHOUT the lock at t=31s while the lock sits there
964
+ at thirty-one seconds old and still counted as valid. Two watchers, and the
965
+ timeout meant to prevent exactly this was twice as far away as the waiter
966
+ could see.
967
+
968
+ `* 2` rather than `* 3`: equal to the budget would mean breaking the lock on
969
+ the final attempt with no attempts left to take it, which is the same
970
+ unlocked start with an extra step. Twenty seconds leaves ten to acquire.
971
+
972
+ The ceiling itself is right, and worth restating because it is load-bearing.
973
+ Rivals are signalled in one pass and waited for in another, so their five
974
+ second waits OVERLAP -- five rivals cost about five seconds, not twenty-five
975
+ -- and a stale incumbent adds one more five. Ten is the worst legitimate
976
+ hold, thirty is three times it, and twenty sits between them.
977
+ */
978
+ const HELD_TOO_LONG_MS = LONGEST_HOLD_MS * 2;
880
979
  // Ten steps is a second. Writing a forty-byte file does not take a second, so
881
980
  // anything still unparseable after that is genuinely broken rather than in
882
981
  // flight.
@@ -915,7 +1014,23 @@ async function claimStartup() {
915
1014
  }
916
1015
  };
917
1016
  } catch (error) {
918
- if (error?.code !== 'EEXIST') return () => {};
1017
+ if (error?.code !== 'EEXIST') {
1018
+ /*
1019
+ PROCEEDING WITHOUT THE LOCK, and saying so.
1020
+
1021
+ Any error that is not "somebody already holds it" -- EACCES on the
1022
+ lock file, EROFS, ENOSPC, a lockRoot that is not a directory -- ends
1023
+ here, and this used to return silently. A daemon that could not take
1024
+ the lock then started anyway and looked exactly like one that had
1025
+ taken it.
1026
+ */
1027
+ complain(
1028
+ `could not take the startup lock (${error?.code ?? error?.message ?? 'unknown'}) ` +
1029
+ `at ${startupLockPath}. Starting WITHOUT it, so two watchers are possible; ` +
1030
+ 'the reconciliation after registration is what stops that being permanent.',
1031
+ );
1032
+ return () => {};
1033
+ }
919
1034
 
920
1035
  let held;
921
1036
  try {
@@ -938,6 +1053,11 @@ async function claimStartup() {
938
1053
  */
939
1054
  unreadable += 1;
940
1055
  if (unreadable > UNREADABLE_BEFORE_DEBRIS) {
1056
+ complain(
1057
+ `the startup lock has been unreadable for ${unreadable * WAIT_STEP_MS}ms; ` +
1058
+ 'treating it as debris and deleting it. If a live holder wrote it, ' +
1059
+ 'this is the moment two watchers become possible.',
1060
+ );
941
1061
  try {
942
1062
  unlinkSync(startupLockPath);
943
1063
  } catch {
@@ -957,7 +1077,21 @@ async function claimStartup() {
957
1077
  alive = false;
958
1078
  }
959
1079
 
960
- if (!alive || Date.now() - (held.at ?? 0) > HELD_TOO_LONG_MS) {
1080
+ const heldFor = Date.now() - (held.at ?? 0);
1081
+ if (!alive || heldFor > HELD_TOO_LONG_MS) {
1082
+ /*
1083
+ BREAKING SOMEBODY ELSE'S LOCK is the most consequential thing in this
1084
+ function and it used to happen in silence. The read-decide-unlink is
1085
+ not atomic: between believing the holder is gone and deleting the
1086
+ file, the holder can have released it and a third process taken it,
1087
+ and what gets deleted is a live lock. That is the shape that produces
1088
+ two watchers, and without this line there is nothing afterwards that
1089
+ says it happened.
1090
+ */
1091
+ say(
1092
+ `breaking the startup lock held by pid ${held.pid} ` +
1093
+ (alive ? `after ${heldFor}ms, which is longer than any legitimate hold` : '(no such process)'),
1094
+ );
961
1095
  try {
962
1096
  unlinkSync(startupLockPath);
963
1097
  } catch {
@@ -970,9 +1104,24 @@ async function claimStartup() {
970
1104
  }
971
1105
  }
972
1106
 
973
- // Outlasted three times the longest legitimate hold and still never got it,
974
- // so something is wrong that waiting will not fix. Carry on unlocked rather
975
- // than never watching: being unable to serialise is not a reason to refuse.
1107
+ /*
1108
+ Outlasted three times the longest legitimate hold and still never got it,
1109
+ so something is wrong that waiting will not fix. Carry on unlocked rather
1110
+ than never watching: being unable to serialise is not a reason to refuse.
1111
+
1112
+ LOUDLY, though. This is the other way two watchers happen, and it was as
1113
+ silent as the first -- so a log showing two `started` lines and nothing
1114
+ else was consistent with this, with the fail-open above, and with the lock
1115
+ working perfectly and something else being wrong. Three explanations, no
1116
+ evidence, which is why two attempts at diagnosing the real incident got
1117
+ nowhere.
1118
+ */
1119
+ complain(
1120
+ `waited ${(WAIT_ATTEMPTS * WAIT_STEP_MS) / 1000}s for the startup lock at ` +
1121
+ `${startupLockPath} and never got it. Starting WITHOUT it, so two watchers ` +
1122
+ 'are possible; the reconciliation after registration is what stops that ' +
1123
+ 'being permanent.',
1124
+ );
976
1125
  return () => {};
977
1126
  }
978
1127