meerkat-taskpanel 0.1.0 → 0.1.1

package/.claude-plugin/marketplace.json

@@ -3,7 +3,7 @@
   "owner": { "name": "tanyu216" },
   "metadata": {
     "description": "Task management board for AI Agent teams.",
-    "version": "0.1.0"
+    "version": "0.1.1"
   },
   "plugins": [
     {

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "meerkat-taskpanel",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Task management board for AI Agent teams.",
   "author": { "name": "tanyu216" },
   "license": "MIT",

package/CHANGELOG.md

@@ -7,6 +7,17 @@ project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.1.1] - 2026-10-27
+
+### Fixed
+
+- The `taskd` keepalive guard now writes its launchd/systemd units under the install root
+  (`<home>/.meerkat-taskpanel/scheduling/`) instead of a stray `<home>/taskpanel`
+  directory beside it.
+- The guard is no longer loaded when a board is already answering `/health` at the runtime
+  pointer's address. A second `taskd` on that port only restarted into `EADDRINUSE`; the
+  install now leaves the running board alone and reports what it found.
+
 ## [0.1.0] - 2026-10-27
 
 First public release.
@@ -117,5 +128,6 @@ First public release.
 - `issue get` shows the card title.
 - The subscriber unit points at the event hub instead of a direct stream.
 
-[Unreleased]: https://github.com/tanyu216/meerkat-taskpanel/compare/v0.1.0...HEAD
+[0.1.1]: https://github.com/tanyu216/meerkat-taskpanel/releases/tag/v0.1.1
+[Unreleased]: https://github.com/tanyu216/meerkat-taskpanel/compare/v0.1.1...HEAD
 [0.1.0]: https://github.com/tanyu216/meerkat-taskpanel/releases/tag/v0.1.0

package/docs/install.md

@@ -344,12 +344,12 @@ a daemon for you (the [Scheduling units](#scheduling-units-claude-codex-pi) abov
 applies **only to the `taskd` service guard**: the `meerkat-loop` supervisor's units are
 still written and left for you to load, and OpenClaw still gets none.
 
-**Where it lands** — a neutral directory, deliberately *not* the loop units'
+**Where it lands** — under the install root, deliberately *not* the loop units'
 `<agent-dir>/scheduling/`, so re-installing an agent kind's loop units never touches it:
 
 ```text
-<prefix>/taskpanel/scheduling/launchd/com.meerkat-taskpanel.taskd.plist
-<prefix>/taskpanel/scheduling/systemd/meerkat-taskpanel-taskd.service
+<prefix>/.meerkat-taskpanel/scheduling/launchd/com.meerkat-taskpanel.taskd.plist
+<prefix>/.meerkat-taskpanel/scheduling/systemd/meerkat-taskpanel-taskd.service
 ```
 
 `<prefix>` is `--prefix` (default `$HOME`). There is **one guard per machine** — and
@@ -362,10 +362,10 @@ separate flag:
 
 ```bash
 # macOS
-launchctl bootstrap gui/$UID <prefix>/taskpanel/scheduling/launchd/com.meerkat-taskpanel.taskd.plist
+launchctl bootstrap gui/$UID <prefix>/.meerkat-taskpanel/scheduling/launchd/com.meerkat-taskpanel.taskd.plist
 # Linux (user unit)
 mkdir -p ~/.config/systemd/user
-cp <prefix>/taskpanel/scheduling/systemd/meerkat-taskpanel-taskd.service ~/.config/systemd/user/
+cp <prefix>/.meerkat-taskpanel/scheduling/systemd/meerkat-taskpanel-taskd.service ~/.config/systemd/user/
 systemctl --user enable --now meerkat-taskpanel-taskd.service
 ```
 
@@ -383,6 +383,15 @@ and names the log to read:
 taskd guard: loaded (com.meerkat-taskpanel.taskd, pid …); /health did not answer within 10000ms — read <dataDir>/logs/taskd.log
 ```
 
+A board that is **already serving** — the runtime pointer's address answers `/health`
+before the guard is loaded — is left alone. Loading a second `taskd` on that port is not a
+keepalive; it is an `EADDRINUSE` restart loop. The units are still written, nothing is
+loaded, and the install says:
+
+```text
+taskd guard: not loaded — a board is already serving http://127.0.0.1:9527 (pid …); stop it and re-run to install the guard
+```
+
 Neither line fails the install. The unit names the **absolute** node that ran the install,
 so a node that lives only under nvm or Homebrew still starts the server — see
 [`scheduling.md § The taskd guard (keepalive)`](scheduling.md#the-taskd-guard-keepalive).
@@ -428,7 +437,7 @@ plain `kill` is not enough — use the supervisor's own stop:
 ```bash
 # macOS
 launchctl bootout gui/$UID/com.meerkat-taskpanel.taskd
-rm <prefix>/taskpanel/scheduling/launchd/com.meerkat-taskpanel.taskd.plist
+rm <prefix>/.meerkat-taskpanel/scheduling/launchd/com.meerkat-taskpanel.taskd.plist
 # Linux
 systemctl --user disable --now meerkat-taskpanel-taskd.service
 rm ~/.config/systemd/user/meerkat-taskpanel-taskd.service

package/docs/scheduling.md

@@ -844,12 +844,12 @@ write lock (R1: one `taskd` per data directory).
 #### Where the unit lands (ownership separation)
 
 ```text
-<prefix>/taskpanel/scheduling/launchd/com.meerkat-taskpanel.taskd.plist
-<prefix>/taskpanel/scheduling/systemd/meerkat-taskpanel-taskd.service
+<prefix>/.meerkat-taskpanel/scheduling/launchd/com.meerkat-taskpanel.taskd.plist
+<prefix>/.meerkat-taskpanel/scheduling/systemd/meerkat-taskpanel-taskd.service
 ```
 
-A **neutral** directory (`<prefix>` is `install.sh --prefix`, default `$HOME`),
-deliberately **not** `<agent-dir>/scheduling/` where the loop's `ping`/`continue` units
+The install root (`<prefix>/.meerkat-taskpanel/`; `<prefix>` is `install.sh --prefix`,
+default `$HOME`), deliberately **not** `<agent-dir>/scheduling/` where the loop's `ping`/`continue` units
 live ([Scheduling units](install.md#scheduling-units-claude-codex-pi)). Re-installing a
 agent kind's loop units never touches this directory, and the two are never confused for one
 another.
@@ -980,7 +980,7 @@ nothing.
 # ~/.config/systemd/user/ and enables it immediately.
 #
 #   mkdir -p ~/.config/systemd/user
-#   cp <prefix>/taskpanel/scheduling/systemd/meerkat-taskpanel-taskd.service ~/.config/systemd/user/
+#   cp <prefix>/.meerkat-taskpanel/scheduling/systemd/meerkat-taskpanel-taskd.service ~/.config/systemd/user/
 #   systemctl --user enable --now meerkat-taskpanel-taskd.service
 #
 # ExecStart names the ABSOLUTE node that rendered this unit — never
@@ -1039,11 +1039,11 @@ user switch**. `install.sh` writes the unit and then loads/enables it:
 
 ```bash
 # macOS
-launchctl bootstrap gui/$UID <prefix>/taskpanel/scheduling/launchd/com.meerkat-taskpanel.taskd.plist
+launchctl bootstrap gui/$UID <prefix>/.meerkat-taskpanel/scheduling/launchd/com.meerkat-taskpanel.taskd.plist
 #   (older systems: launchctl load -w <plist>)
 # Linux (user unit)
 mkdir -p ~/.config/systemd/user
-cp <prefix>/taskpanel/scheduling/systemd/meerkat-taskpanel-taskd.service ~/.config/systemd/user/
+cp <prefix>/.meerkat-taskpanel/scheduling/systemd/meerkat-taskpanel-taskd.service ~/.config/systemd/user/
 systemctl --user enable --now meerkat-taskpanel-taskd.service
 ```
 
@@ -1078,6 +1078,15 @@ taskd guard: loaded (com.meerkat-taskpanel.taskd, pid 17388); /health did not an
 Neither line fails the install (the agent-kind skills are installed either way), but only the
 first one claims the guard works.
 
+A board that is **already answering** at the runtime pointer's address is a third case, and
+it is not loaded over: a second `taskd` on the same port is an `EADDRINUSE` restart loop, not
+a keepalive. The units are written, the load is skipped, and the report names the running
+board:
+
+```text
+taskd guard: not loaded — a board is already serving http://127.0.0.1:9527 (pid …); stop it and re-run to install the guard
+```
+
 A **second board** is where the install has to be careful, because the guard is one per
 machine ([One guard per machine](#one-guard-per-machine)): on Linux the file systemd reads
 `~/.config/systemd/user/meerkat-taskpanel-taskd.service`, and that file *is* the machine's
@@ -1112,7 +1121,7 @@ To stop and remove the guard:
 ```bash
 # macOS
 launchctl bootout gui/$UID/com.meerkat-taskpanel.taskd
-rm <prefix>/taskpanel/scheduling/launchd/com.meerkat-taskpanel.taskd.plist
+rm <prefix>/.meerkat-taskpanel/scheduling/launchd/com.meerkat-taskpanel.taskd.plist
 # Linux
 systemctl --user disable --now meerkat-taskpanel-taskd.service
 rm ~/.config/systemd/user/meerkat-taskpanel-taskd.service

package/install.sh

@@ -206,7 +206,7 @@ Environment (set for each agent-kind installer):
                                  (internal — for tests, not a user option)
 
 The taskd keepalive guard is written and loaded on every install (one unit per
-machine, at <prefix>/taskpanel/scheduling/) — see docs/scheduling.md. It has no
+machine, at <prefix>/.meerkat-taskpanel/scheduling/) — see docs/scheduling.md. It has no
 user flag and no prompt; the bypasses are --no-automation, --dry-run, and the
 test-only MEERKAT_TASKPANEL_SKIP_TASKD_SERVICE above.
 EOF
@@ -219,8 +219,8 @@ die() {
 
 # install_taskd_guard — write the `taskd` keepalive unit and load it (docs/scheduling.md).
 #
-# One unit per **machine**, not per agent kind: it is written once here, to the neutral
-# `<prefix>/taskpanel/scheduling/` directory, and never touched by an agent kind's own
+# One unit per **machine**, not per agent kind: it is written once here, under the install
+# root `<prefix>/.meerkat-taskpanel/scheduling/`, and never touched by an agent kind's own
 # scheduling install. It is also the one unit this installer *loads* rather than
 # only printing a command for — a deliberate, narrow exception to "write the unit,
 # never start a daemon for you". The loop supervisor's units keep that rule.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "meerkat-taskpanel",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "type": "module",
   "workspaces": [
     "web"

package/scripts/install/lib/taskd-guard.mjs

@@ -3,8 +3,8 @@
  * The `taskd` OS-level keepalive unit — "the guard" (`docs/scheduling.md`).
  *
  * `install.sh` calls this once per install, because the guard is **one per
- * machine**, not one per agent kind: it writes both unit templates into a neutral
- * `<prefix>/taskpanel/scheduling/` directory (deliberately *not* the loop units'
+ * machine**, not one per agent kind: it writes both unit templates under the install root
+ * `<prefix>/.meerkat-taskpanel/scheduling/` (deliberately *not* the loop units'
  * `<agent-dir>/scheduling/`, so re-installing an agent kind never touches it) and then
  * loads the one for this platform. It is the single **explicit exception** to
  * the installer's rule that it writes a unit and prints the load command but
@@ -50,6 +50,12 @@
  * exactly the readiness test the CLI applies. A unit that is loaded but not
  * serving reports `loaded … /health did not answer` instead, with the log to read.
  *
+ * **A board that is already running is not loaded over.** Before loading, the address the
+ * runtime pointer names is knocked once. A `/health` answer means a second `taskd` would
+ * only collide on that port (`EADDRINUSE`, a keepalive restart loop), so the units are
+ * written and the load is skipped, with the running board named. The same rule applies to
+ * the guard's own board lazily started by a CLI call: stop it and re-run to hand it over.
+ *
  * **The guard is one per machine, so a second install may have to refuse**
  * (`docs/scheduling.md § One guard per machine`). Because the label and the unit name
  * carry no board segment, the machine has exactly one guard job, and on Linux the file
@@ -175,8 +181,8 @@ export function guardPaths(options = {}) {
     nodeDir: dirname(node),
     serverEntry: join(root, "src", "server", "main.mjs"),
     logFile: join(dataDir, LOGS_DIRNAME, LOG_FILENAME),
-    launchdUnit: join(prefix, "taskpanel", "scheduling", "launchd", `${TASKD_LABEL}.plist`),
-    systemdUnit: join(prefix, "taskpanel", "scheduling", "systemd", TASKD_UNIT),
+    launchdUnit: join(prefix, ".meerkat-taskpanel", "scheduling", "launchd", `${TASKD_LABEL}.plist`),
+    systemdUnit: join(prefix, ".meerkat-taskpanel", "scheduling", "systemd", TASKD_UNIT),
     pointerFile: resolveRuntimePointerPath({ env }),
   };
 }
@@ -531,6 +537,26 @@ export async function installGuard(options = {}) {
   const already = runStep(plan.loadedProbe, run);
   if (already.ok) report.pid = waitForPid(plan, run, pidWaitMs);
 
+  // A board that is **already answering** owns the address this unit would bind. Loading
+  // the guard then does not create a keepalive — it starts a second server on an occupied
+  // port, which is an EADDRINUSE restart loop, not a board. The runtime pointer is the
+  // running board's own statement of its address, and `/health` is the same readiness test
+  // the CLI trusts, so one knock settles it. The unit files stay written (the operator can
+  // load them after stopping the board); nothing is loaded and nothing is claimed.
+  if (!already.ok) {
+    const running = (options.readPointerFn ?? readPointer)({ path: paths.pointerFile });
+    const runningUrl = running !== null && typeof running.url === "string" ? running.url : null;
+    if (runningUrl !== null && (await (options.healthProbe ?? probeHealth)(runningUrl))) {
+      report.state = "running";
+      report.url = runningUrl;
+      report.reason = `a board is already serving ${runningUrl}`;
+      log(
+        `taskd guard: not loaded — a board is already serving ${runningUrl}${running.pid ? ` (pid ${running.pid})` : ""}; stop it and re-run to install the guard`,
+      );
+      return report;
+    }
+  }
+
   // The board this run would install, read back from the file that would be copied —
   // what actually lands, not a re-derivation of it.
   const mine = unitBoard(readFileSync(kind === "launchd" ? paths.launchdUnit : paths.systemdUnit, "utf8"));
@@ -805,7 +831,7 @@ function waitForPid(plan, run, budgetMs) {
 const USAGE = `Usage: node scripts/install/lib/taskd-guard.mjs install --prefix <dir> [--root <tree>] [--data-dir <dir>] [--force]
 
 Writes the taskd keepalive unit (launchd + systemd) under
-<dir>/taskpanel/scheduling/, then loads this platform's one, waits for its
+<dir>/.meerkat-taskpanel/scheduling/, then loads this platform's one, waits for its
 board to answer /health, and reports what happened.
 --root names the program tree the unit runs (default: this checkout);
 --data-dir pins TASKD_DATA_DIR in the unit (used by --target server).

package/scripts/install/templates/taskd/systemd/meerkat-taskpanel-taskd.service

@@ -10,7 +10,7 @@
 # ~/.config/systemd/user/ and enables it immediately.
 #
 #   mkdir -p ~/.config/systemd/user
-#   cp <prefix>/taskpanel/scheduling/systemd/meerkat-taskpanel-taskd.service ~/.config/systemd/user/
+#   cp <prefix>/.meerkat-taskpanel/scheduling/systemd/meerkat-taskpanel-taskd.service ~/.config/systemd/user/
 #   systemctl --user enable --now meerkat-taskpanel-taskd.service
 #
 # ExecStart names the ABSOLUTE node that rendered this unit — never

package/src/foundation/constants.mjs

@@ -12,7 +12,7 @@
 
 export const CLI_NAME = "taskctl";
 export const SKILL_NAME = "meerkat-taskpanel";
-export const VERSION = "0.1.0";
+export const VERSION = "0.1.1";
 
 /**
  * The board's **contract schema generation** — which generation of the API/wire