axstack 0.36.0 → 0.36.1

package/README.md

@@ -126,10 +126,13 @@ Eligible own PRs use guarded automatic merge; see [merge boundaries, exclusions,
 ## Some notes
 
 - T3 Code is the only supported active runtime. Axstack adds no daemon or runtime
-  database. The exception is one opt-in systemd user timer `axstack-default-sync`,
-  running a stateless script that rewrites only T3 `defaultModelSelection`.
-  It has no workflow state and launches no agent; see
-  [Host operations](docs/host-operations.md#new-chat-default-sync).
+  database. The exceptions are exactly two opt-in systemd user timers:
+  `axstack-default-sync` rewrites only T3 `defaultModelSelection`, and
+  `axstack-single-server` removes duplicate `t3 serve` process trees for one
+  base dir while keeping the recorded server. Both run stateless scripts, keep
+  no workflow state and launch no agent; see
+  [New-chat default sync](docs/host-operations.md#new-chat-default-sync) and
+  [Single T3 server](docs/host-operations.md#single-t3-server).
 - The recorded owning watch thread merges eligible own PRs; excluded PRs use a merge card.
 - This is an early project; expect the workflows to evolve.
 

package/docs/host-operations.md

@@ -44,9 +44,10 @@ the affected operation. Provider/model routing, Linear documents through the
 executor MCP, and live schedule behavior need separate preflights.
 
 Installation creates no production schedule and never enables a timer.
-Axstack allows one opt-in systemd user timer `axstack-default-sync` as the
-scheduler exception: it runs a stateless script that rewrites only T3
-`defaultModelSelection`, has no workflow state and launches no agent.
+Axstack allows exactly two opt-in systemd user timers as scheduler exceptions:
+`axstack-default-sync` rewrites only T3 `defaultModelSelection`, and
+`axstack-single-server` removes duplicate server processes for one base dir.
+Both run stateless scripts, keep no workflow state and launch no agent.
 Every verified own-PR publication arms or joins the driver's chat-run watch.
 Its bound T3 schedule uses the cadence in [Chat-run watch activation](#chat-run-watch-activation).
 See [Chat-run PR watch](workflows.md#chat-run-pr-watch) for authority, schedule identity and stop conditions.
@@ -204,8 +205,9 @@ retirement. No broad scratch deletion or forced worktree removal applies.
 Manual review and user-driven `axstack-watch` remain outside this schedule.
 Requested peer reviews cover any accessible repository. T3 owns schedules,
 threads, runs, and delegated tasks; Axstack adds no queue engine, cursor files,
-or historical runtime fallback. The only scheduler exception is the opt-in
-systemd user timer described in [New-chat default sync](#new-chat-default-sync).
+or historical runtime fallback. The only scheduler exceptions are the two opt-in
+systemd user timers described in [New-chat default sync](#new-chat-default-sync)
+and [Single T3 server](#single-t3-server).
 
 ## Review automation
 
@@ -282,3 +284,73 @@ Rollback: remove the pool drop-in, reload, and restore the full selection in T3
 The sibling `<settings>.axstack-default-sync.lock` directory prevents overlap
 (unchanged/locked). Empty locks older than sixty seconds are removed and retried
 once; fresh contention reports locked.
+
+## Single T3 server
+
+This opt-in timer checks once per minute for this user's `t3 serve` processes
+with the selected base dir (target default `$HOME/.t3`). Each server's base dir
+comes from its `--base-dir <dir>` or `--base-dir=<dir>` flag, then its own
+`T3CODE_HOME`, then its own `$HOME/.t3`, reading the latter values from that
+process's environment. An unreadable or missing environment without an explicit
+flag, or missing base-dir values, makes the whole run hold and kill nothing.
+It keeps the pid recorded in `<base>/userdata/server-runtime.json`.
+With zero or one known matching server it does nothing; with duplicates but no
+valid readable keeper it holds. Duplicate servers must have started strictly
+before the keeper, comparing field 22 (`starttime`) of `/proc/<pid>/stat`.
+An unknown start time or any duplicate started at or after the keeper holds
+the whole run, preserving a possible starting replacement. The script also
+holds if its own pid or an ancestor appears in the planned victim set.
+Otherwise it snapshots descendants before killing each duplicate server first,
+then its children with SIGKILL. The keeper and its descendants are protected.
+It starts no server, reads no database and interrupts no runs automatically.
+
+Preview the one-line JSON decision without killing or notifying:
+
+```sh
+bun ~/.agents/skills/axstack/scripts/single-server.js --dry-run
+```
+
+`--base-dir <dir>` selects a different base dir; `--proc-root <dir>` supplies
+a process-tree fixture (default `/proc`). `--help` lists the flags. Decisions
+are `unchanged`, `hold`, `would-kill` or `killed`, with reason, keeper, matching
+server pids and killed pids (proposed victims in dry-run). Non-ESRCH kill failures
+add their pids to `failed`; remaining kills continue, successful kills still
+notify if configured, and the command exits 1. Exit 0 includes holds;
+exit 1 reports invalid input, discovery, kill or notification failure.
+
+Under host-mutation authority, copy both assets and enable the timer:
+
+```sh
+mkdir -p ~/.config/systemd/user
+cp ~/.agents/skills/axstack/systemd/axstack-single-server.service ~/.config/systemd/user/axstack-single-server.service
+cp ~/.agents/skills/axstack/systemd/axstack-single-server.timer ~/.config/systemd/user/axstack-single-server.timer
+systemctl --user daemon-reload
+systemctl --user enable --now axstack-single-server.timer
+systemctl --user list-timers axstack-single-server.timer
+journalctl --user -u axstack-single-server.service
+```
+
+Installation only copies assets; it never enables either timer. The single-server
+timer starts one minute after user-manager startup and repeats every minute.
+Override Bun/skills paths or add `--base-dir` through the service's `ExecStart`
+drop-in, clearing the existing `ExecStart` first.
+
+To notify only after a kill, use `systemctl --user edit axstack-single-server.service`
+and add a per-host command, then reload:
+
+```ini
+[Service]
+Environment="AXSTACK_SINGLE_SERVER_NOTIFY=hermes send --to telegram --quiet"
+```
+
+The VPS has Hermes locally; other hosts can use
+`Environment="AXSTACK_SINGLE_SERVER_NOTIFY=ssh '<relay-host>' hermes send --to telegram --quiet"`.
+Replace `<relay-host>` with the authorized gateway's hostname.
+The script runs the command via `sh -c`, sending a short message on stdin with
+hostname, kept pid and killed pids. It notes that runs started by the killed
+server may remain `running` and need `t3_thread_interrupt`. Notification failure
+exits 1 after the kills; command output is suppressed. Dry-run, unchanged and
+hold decisions never notify. Verify delivery under the host's notification authority.
+
+Disable with `systemctl --user disable --now axstack-single-server.timer` and
+stop any active one-shot with `systemctl --user stop axstack-single-server.service`.

package/docs/installation.md

@@ -96,10 +96,13 @@ Run these with Bun from the installed `<skills-dir>/axstack/scripts/` directory:
 `resolve-models.js` (model IDs), `pick-instance.js` (dispatch account),
 `pr-digest.js` (PR discovery), `archive-evidence.js` (evidence archive), and
 `sync-default.js [--settings <path>] [--dry-run]` (New-chat default; `AXSTACK_SYNC_POOL` opts into cross-driver rotation).
+`single-server.js [--base-dir <dir>] [--proc-root <dir>] [--dry-run]` removes
+duplicate `t3 serve` process trees while keeping the recorded runtime pid.
 `account-usage.js` shares usage retrieval and the five-minute cache between
 picker and sync. The opt-in systemd user unit files ship in `axstack/systemd/`;
-installation copies them as assets and never enables the timer.
-See [Host operations](host-operations.md#new-chat-default-sync) for activation.
+installation copies them as assets and never enables either timer.
+See [New-chat default sync](host-operations.md#new-chat-default-sync) and
+[Single T3 server](host-operations.md#single-t3-server) for activation.
 
 ## Role presets
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "axstack",
-  "version": "0.36.0",
+  "version": "0.36.1",
   "description": "Axstack installer and setup CLI: installs owned chat skills and role data, configures supported harness settings, and checks T3 Code capabilities.",
   "keywords": [
     "claude-code",

package/skills/axstack/scripts/single-server.js

@@ -0,0 +1,164 @@
+import * as fs from 'node:fs';
+
+function serverBase(procRoot, pid, argv) {
+  let base;
+  for (let i = 2; i < argv.length; i++) {
+    if (argv[i] === '--base-dir') base = argv[++i];
+    else if (argv[i].startsWith('--base-dir=')) base = argv[i].slice('--base-dir='.length);
+  }
+  if (base !== undefined) return base || null;
+  try {
+    const environ = fs.readFileSync(`${procRoot}/${pid}/environ`, 'utf8').split('\0');
+    const value = (key) => environ.find((entry) => entry.startsWith(`${key}=`))?.slice(key.length + 1);
+    return value('T3CODE_HOME') || (value('HOME') ? `${value('HOME')}/.t3` : null);
+  } catch { return null; }
+}
+
+function discover(procRoot, uid, baseDir) {
+  const processes = new Map();
+  const servers = [];
+  let unknownBase = false;
+  const pids = fs.readdirSync(procRoot).filter((name) => /^[1-9]\d*$/.test(name)).map(Number).sort((a, b) => a - b);
+  for (const pid of pids) {
+    try {
+      const status = fs.readFileSync(`${procRoot}/${pid}/status`, 'utf8');
+      const parent = /^PPid:\s+(\d+)/m.exec(status);
+      const user = /^Uid:\s+(\d+)/m.exec(status);
+      if (!parent || !user) throw new Error('invalid process status');
+      processes.set(pid, Number(parent[1]));
+      if (Number(user[1]) !== uid) continue;
+      const argv = fs.readFileSync(`${procRoot}/${pid}/cmdline`, 'utf8').split('\0');
+      if (argv[0].split('/').at(-1) !== 't3' || argv[1] !== 'serve') continue;
+      const base = serverBase(procRoot, pid, argv);
+      if (base === null) unknownBase = true;
+      else if (base === baseDir) servers.push(pid);
+    } catch (error) {
+      // Processes can exit during discovery; every other scan failure prevents kills.
+      if (!['ENOENT', 'ESRCH'].includes(error.code)) throw error;
+    }
+  }
+  return { processes, servers, unknownBase };
+}
+
+function descendants(pid, processes) {
+  const found = new Set([pid]);
+  for (const parent of found) {
+    for (const [child, ppid] of processes) if (ppid === parent) found.add(child);
+  }
+  found.delete(pid);
+  return [...found];
+}
+
+function replacementHold(procRoot, servers, keeper) {
+  const starts = new Map(servers.map((pid) => {
+    let start = null;
+    try {
+      const stat = fs.readFileSync(`${procRoot}/${pid}/stat`, 'utf8');
+      const end = stat.lastIndexOf(')');
+      // The comm field can contain spaces and parentheses; field 22 is index 19 after it.
+      const value = end < 0 ? '' : stat.slice(end + 1).trim().split(/\s+/)[19];
+      if (/^\d+$/.test(value)) start = BigInt(value);
+    } catch { /* Unknown age never authorizes a kill. */ }
+    return [pid, start];
+  }));
+  if ([...starts.values()].includes(null)) return 'unknown-start-time';
+  if (servers.some((pid) => pid !== keeper && starts.get(pid) >= starts.get(keeper))) return 'possible-replacement';
+  return null;
+}
+
+export async function run(args = [], {
+  env = process.env, uid = process.getuid(), kill = process.kill, spawn = Bun.spawn,
+  hostname = () => fs.readFileSync('/proc/sys/kernel/hostname', 'utf8').trim(), output = console.log,
+} = {}) {
+  let decision = { action: 'hold', reason: 'invalid-input', keeper: null, servers: [], killed: [] };
+  let failure = 'invalid-input';
+  let code = 0;
+  try {
+    let baseDir = `${env.HOME}/.t3`;
+    let procRoot = '/proc';
+    let dryRun = false;
+    const seen = new Set();
+    for (let i = 0; i < args.length; i++) {
+      const flag = args[i];
+      if (flag === '--help' && args.length === 1) {
+        output('Usage: bun single-server.js [--base-dir DIR] [--proc-root DIR] [--dry-run] [--help]\n'
+          + 'Defaults: $HOME/.t3 and /proc. SIGKILL duplicate t3 serve servers and their descendants;\n'
+          + 'keep the runtime pid. --dry-run reports only. AXSTACK_SINGLE_SERVER_NOTIFY runs via sh -c after kills.');
+        return 0;
+      }
+      if (seen.has(flag)) throw new Error('duplicate flag');
+      seen.add(flag);
+      if (flag === '--dry-run') dryRun = true;
+      else if (['--base-dir', '--proc-root'].includes(flag) && args[i + 1] && !args[i + 1].startsWith('--')) {
+        const value = args[++i];
+        if (flag === '--base-dir') baseDir = value;
+        else procRoot = value;
+      } else throw new Error('invalid flag');
+    }
+    if (!env.HOME) throw new Error('missing home');
+    failure = 'scan-failed';
+    const { processes, servers, unknownBase } = discover(procRoot, uid, baseDir);
+    decision.servers = servers;
+    let runtimePid;
+    try { runtimePid = JSON.parse(fs.readFileSync(`${baseDir}/userdata/server-runtime.json`, 'utf8')).pid; }
+    catch { /* Missing, unreadable or malformed runtime data is never authority to kill. */ }
+    if (Number.isSafeInteger(runtimePid) && servers.includes(runtimePid)) decision.keeper = runtimePid;
+    const ageHold = !unknownBase && servers.length > 1 && decision.keeper !== null
+      ? replacementHold(procRoot, servers, decision.keeper) : null;
+    if (unknownBase) decision.reason = 'unknown-base-dir';
+    else if (servers.length < 2) decision = { ...decision, action: 'unchanged', reason: 'single-server' };
+    else if (decision.keeper === null) decision.reason = 'no-valid-keeper';
+    else if (ageHold) decision.reason = ageHold;
+    else {
+      const protectedPids = new Set([decision.keeper, ...descendants(decision.keeper, processes)]);
+      // Snapshot every tree before SIGKILL can reparent children, including other server trees.
+      const trees = servers.filter((pid) => !protectedPids.has(pid))
+        .map((pid) => [pid, ...descendants(pid, processes)]);
+      const roots = trees.filter(([pid]) => !trees.some((tree) => tree[0] !== pid && tree.includes(pid)));
+      const victims = [...new Set(roots.flat())].filter((pid) => !protectedPids.has(pid));
+      const ancestors = new Set([process.pid]);
+      let parent = processes.get(process.pid) ?? process.ppid;
+      while (parent && !ancestors.has(parent)) {
+        ancestors.add(parent);
+        parent = processes.get(parent);
+      }
+      decision.reason = 'duplicate-servers';
+      if (victims.some((pid) => ancestors.has(pid))) decision.reason = 'own-process-tree';
+      else if (dryRun) decision = { ...decision, action: 'would-kill', killed: victims };
+      else {
+        failure = 'kill-failed';
+        for (const pid of victims) {
+          try { kill(pid, 'SIGKILL'); }
+          catch (error) {
+            if (error.code !== 'ESRCH') {
+              decision.failed ??= [];
+              decision.failed.push(pid);
+              code = 1;
+            }
+            continue;
+          }
+          decision.action = 'killed';
+          decision.killed.push(pid);
+        }
+        if (decision.failed?.length) decision.reason = 'kill-failed';
+        else if (!decision.killed.length) decision = { ...decision, action: 'unchanged', reason: 'no-victims' };
+        if (decision.killed.length && env.AXSTACK_SINGLE_SERVER_NOTIFY) {
+          failure = 'notify-failed';
+          const message = `${hostname()}: kept pid ${decision.keeper}; killed pids ${decision.killed.join(', ')}. `
+            + 'Runs started by the killed server may stay running and need t3_thread_interrupt.\n';
+          const child = spawn(['sh', '-c', env.AXSTACK_SINGLE_SERVER_NOTIFY], {
+            stdin: new Blob([message]), stdout: 'ignore', stderr: 'ignore', env,
+          });
+          if (await child.exited !== 0) throw new Error('notification failed');
+        }
+      }
+    }
+  } catch {
+    decision.reason = failure;
+    code = 1;
+  }
+  output(JSON.stringify(decision));
+  return code;
+}
+
+if (import.meta.main) process.exitCode = await run(process.argv.slice(2));

package/skills/axstack/systemd/axstack-single-server.service

@@ -0,0 +1,8 @@
+[Unit]
+Description=Keep the recorded T3 server and remove duplicate server trees
+
+[Service]
+Type=oneshot
+Environment=PATH=%h/.bun/bin:/usr/local/bin:/usr/bin:/bin
+UMask=0077
+ExecStart=/usr/bin/env bun %h/.agents/skills/axstack/scripts/single-server.js

package/skills/axstack/systemd/axstack-single-server.timer

@@ -0,0 +1,10 @@
+[Unit]
+Description=Check for duplicate T3 servers every minute
+
+[Timer]
+OnStartupSec=1min
+OnUnitActiveSec=1min
+Unit=axstack-single-server.service
+
+[Install]
+WantedBy=timers.target