refactor: remove daemon

[chrisleekr]

I don't think daemon is useful at all. And I am hesitating to install daemon.

Remove from it.

[chrisleekr]

TL;DR — the daemon is already gone from main; it was never released

The code removal you're asking for already happened in
#192 (c8dc086, merged
2026-06-21) — 50+ files, the whole src/daemon/ tree, src/core/ipc.ts,
sync-queue.ts, watcher.ts, the three OS installers, the [sync] config
section and all the docs.

The reason you still see a daemon is that c8dc086 is not an ancestor of any
published tag:

$ git merge-base --is-ancestor c8dc086 v0.1.14  →  NO — release PREDATES removal

Fact	Value	Source
Latest npm version	0.1.14, published 2026-06-12	npm view @chrisleekr/agentsync time
Daemon removal merged	2026-06-21 (9 days later)	c8dc086
src/daemon/* present in v0.1.14?	Yes — installer-{macos,linux,windows}.ts, index.ts	git ls-tree v0.1.14
daemon wired into CLI in v0.1.14?	Yes — src/cli.ts:31 daemon: daemonCommand	git show v0.1.14:src/cli.ts
Blocker	PR #183 chore(main): release 0.1.15 — open since 2026-06-20, MERGEABLE / CLEAN, never merged	gh pr view 183

So bun install -g @chrisleekr/agentsync today installs the full daemon
subsystem. Merging the release PR is the actual fix for the reported
symptom.

Residual references to the word "daemon" on main are all legitimate and must
not be touched: CHANGELOG.md (historical), docker/e2e/* (that's Git's
own git daemon transport for scenario 17), and two migration comments in
vault.ts explaining that the legacy [sync] key is now stripped.

---

Two real defects the removal left behind

Defect 1 — the pending changelog advertises features that no longer exist

PR #183's generated changelog still lists:

• feat(daemon): durable health state, divergence escalation, staleness checks, watcher pre-filter (#188)
• feat(tui): add Config tab and surface daemon staleness on the Dashboard (#189)

…and does not mention #192 at all. Cause: release-please's node
release-type hides refactor from the changelog by default
(ChangelogSection.hidden),
and c8dc086's subject is a plain refactor(daemon): with no ! and no
BREAKING CHANGE: footer. Shipping #183 as-is publishes release notes that
promise a daemon health subsystem the binary does not contain.

The version number is wrong for the same reason. Per the repo's
release-please-config.json:

• bump-minor-pre-major: true → "BREAKING CHANGE only bumps semver minor if version < 1.0.0"
• bump-patch-for-minor-pre-major: true → "feat commits bump semver patch instead of minor if version < 1.0.0"

A refactor with no breaking footer contributes nothing, so release-please
computed 0.1.15 (patch) for a release that removes an entire command tree
and a config section. With a proper breaking footer it computes 0.2.0.

Defect 2 — orphaned OS service registrations (the only genuine code work left)

agentsync daemon install on ≤0.1.14 registered a supervised OS service.
Deleting the code cannot unregister it, and 0.1.15 removes the only command
that could (agentsync daemon uninstall). The leftovers, with exact
identifiers read from v0.1.14:

OS	Artifact	Supervisor directive	Consequence after upgrade
macOS	~/Library/LaunchAgents/com.agentsync.daemon.plist	KeepAlive = true	Guaranteed respawn loop — KeepAlive true relaunches regardless of exit status; launchd throttles to ~1 relaunch/10s. Also writes ~/Library/Logs/AgentSync/agentsync.{out,err}.log
Linux	~/.config/systemd/user/agentsync.service	Restart=on-failure, RestartSec=5	Respawn loop iff the binary exits non-zero on the now-unknown daemon _run subcommand; journal spam either way
Windows	Scheduled task AgentSync	—	Task remains registered and fails on each trigger
Unix	~/.agentsync/daemon.sock (or $AGENTSYNC_DIR/daemon.sock)	—	Inert stale socket; useful as evidence the daemon ran here

Each service's ExecStart / ProgramArguments ends in daemon _run, which
0.1.15's citty root command no longer defines.

Non-issue, verified: a stale [sync] section in an existing
agentsync.toml is already safe. AgentSyncConfigSchema is not .strict()
(src/config/schema.ts:88), so Zod strips the unknown key instead of throwing —
confirmed by the migration comment at src/commands/vault.ts:113. No work needed.

---

Flow

Why the issue exists

flowchart TD
    UserInstall["User runs<br/>bun install -g @chrisleekr/agentsync"]:::actor
    NpmLatest["npm dist-tag latest = 0.1.14<br/>published 2026-06-12"]:::bad
    ShipsDaemon["Binary still ships src/daemon/*<br/>and agentsync daemon install"]:::bad
    IssueFiled["Issue #205<br/>hesitating to install daemon"]:::bad
    MainHead["origin/main a25a7c1<br/>daemon fully removed by c8dc086<br/>merged 2026-06-21"]:::good
    ReleasePR["release-please PR #183<br/>chore: release 0.1.15<br/>OPEN since 2026-06-20, MERGEABLE"]:::blocked

    UserInstall --> NpmLatest --> ShipsDaemon --> IssueFiled
    MainHead -->|"awaiting release"| ReleasePR
    ReleasePR -->|"unmerged, so latest is stale"| NpmLatest

    classDef actor fill:#ecf0f1,color:#2c3e50
    classDef bad fill:#c0392b,color:#ffffff
    classDef good fill:#1e8449,color:#ffffff
    classDef blocked fill:#b9770e,color:#ffffff

Loading

The orphaned-service gap and the fix

flowchart TD
    RanInstall["Machine ran agentsync daemon install<br/>on 0.1.14 or earlier"]:::actor
    MacPlist["macOS LaunchAgent com.agentsync.daemon<br/>KeepAlive = true"]:::bad
    LinuxUnit["Linux user unit agentsync.service<br/>Restart = on-failure"]:::bad
    WinTask["Windows scheduled task AgentSync"]:::bad
    Upgraded["Upgrade to 0.2.0<br/>agentsync daemon no longer exists"]:::good
    Respawn["Supervisor execs agentsync daemon _run<br/>unknown subcommand, no uninstall path remains"]:::bad
    DoctorCheck["FIX: agentsync doctor check 7<br/>detects the orphan and prints<br/>the exact removal command"]:::good
    Clean["User runs the printed command<br/>orphan gone"]:::good

    RanInstall --> MacPlist --> Upgraded
    RanInstall --> LinuxUnit --> Upgraded
    RanInstall --> WinTask --> Upgraded
    Upgraded --> Respawn --> DoctorCheck --> Clean

    classDef actor fill:#ecf0f1,color:#2c3e50
    classDef bad fill:#c0392b,color:#ffffff
    classDef good fill:#1e8449,color:#ffffff

Loading

---

Implementation plan

Phase 1 — surface refactor in future changelogs

release-please-config.json — add changelog-sections so a removal this size
can never again be invisible. Heading names match release-please's
DEFAULT_HEADINGS.

Before

{
  "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json",
  "release-type": "node",
  "bump-minor-pre-major": true,
  "bump-patch-for-minor-pre-major": true,
  "include-component-in-tag": false,
  "include-v-in-tag": true,
  "packages": {
    ".": {
      "extra-files": [
        {
          "type": "generic",
          "path": "src/cli.ts",
          "search-by-regex": "version: \"([0-9.]+)\",\\s*// x-release-please-version"
        }
      ]
    }
  }
}

After

{
  "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json",
  "release-type": "node",
  "bump-minor-pre-major": true,
  "bump-patch-for-minor-pre-major": true,
  "include-component-in-tag": false,
  "include-v-in-tag": true,
  "changelog-sections": [
    { "type": "feat", "section": "Features" },
    { "type": "fix", "section": "Bug Fixes" },
    { "type": "perf", "section": "Performance Improvements" },
    { "type": "refactor", "section": "Code Refactoring" },
    { "type": "revert", "section": "Reverts" },
    { "type": "docs", "section": "Documentation" },
    { "type": "deps", "section": "Dependencies" },
    { "type": "build", "section": "Build System", "hidden": true },
    { "type": "chore", "section": "Miscellaneous Chores", "hidden": true },
    { "type": "ci", "section": "Continuous Integration", "hidden": true },
    { "type": "style", "section": "Styles", "hidden": true },
    { "type": "test", "section": "Tests", "hidden": true }
  ],
  "packages": {
    ".": {
      "extra-files": [
        {
          "type": "generic",
          "path": "src/cli.ts",
          "search-by-regex": "version: \"([0-9.]+)\",\\s*// x-release-please-version"
        }
      ]
    }
  }
}

Phase 2 — detect orphaned daemon registrations in doctor

Detect-and-instruct, not auto-remove. Rationale: the repo's stated
convention is "Errors over fallbacks — prefer surfacing failures with
actionable guidance over silent retries", and silently running
launchctl bootout / systemctl --user disable as a side effect of a
read-only diagnostic command would violate doctor's "without changing state"
contract (src/commands/doctor.ts:83). This also adds no new command
surface, so it does not partially re-introduce the daemon.

src/commands/doctor.ts — new exported helper, placed beside
buildSkillsDirChecks so it is unit-testable in isolation (same pattern the
deleted buildDaemonHealthCheck used).

Before — imports and the tail of the check list

import { execFile } from "node:child_process";
import { constants } from "node:fs";
import { access, lstat, readdir, stat } from "node:fs/promises";
import { join, relative } from "node:path";
import { promisify } from "node:util";
import { log } from "@clack/prompts";
import { defineCommand } from "citty";
import { formatConfigError, loadConfig, resolveConfigPath } from "../config/loader";
import { AgentPaths } from "../config/paths";
import { resolveRuntimeContext } from "./shared";

    } catch {
      checks.push({
        name: "Credential files in vault",
        status: "warn",
        detail: "Could not scan vault",
      });
    }

    // Print results

After — imports

import { execFile } from "node:child_process";
import { constants } from "node:fs";
import { access, lstat, readdir, stat } from "node:fs/promises";
import { homedir } from "node:os";
import { join, relative } from "node:path";
import { promisify } from "node:util";
import { log } from "@clack/prompts";
import { defineCommand } from "citty";
import { formatConfigError, loadConfig, resolveConfigPath } from "../config/loader";
import { AgentPaths, resolveAgentSyncHome } from "../config/paths";
import { resolveRuntimeContext } from "./shared";

After — new helper (insert after buildSkillsDirChecks)

// Identifiers registered by the pre-0.2.0 daemon installers. Kept as literals
// rather than re-imported, because the modules that defined them were deleted
// with the daemon in #192.
const LEGACY_LAUNCHD_LABEL = "com.agentsync.daemon";
const LEGACY_SYSTEMD_UNIT = "agentsync";
const LEGACY_WINDOWS_TASK = "AgentSync";

/** Existence probe that never throws, matching the style of the checks above. */
async function pathExists(target: string): Promise<boolean> {
  return access(target, constants.F_OK).then(
    () => true,
    () => false,
  );
}

/**
 * Detect an OS service registration left by the removed background daemon.
 *
 * Upgrading cannot unregister what an older version installed, and the command
 * that could uninstall it was deleted with the daemon. macOS `KeepAlive=true`
 * respawns the job regardless of exit status, so the orphan relaunches a binary
 * whose `daemon _run` subcommand no longer exists until the user removes it.
 *
 * Reports rather than removes: `doctor` is documented as inspecting without
 * changing state, and unregistering a service is not a diagnostic.
 *
 * `platform` is a parameter so each branch is unit-testable off its host OS.
 */
export async function buildLegacyDaemonCheck(
  platform: NodeJS.Platform = process.platform,
): Promise<Check> {
  const name = "Legacy daemon leftovers";
  const found: string[] = [];

  if (platform === "darwin") {
    const plist = join(homedir(), "Library", "LaunchAgents", `${LEGACY_LAUNCHD_LABEL}.plist`);
    if (await pathExists(plist)) {
      found.push(
        `LaunchAgent ${plist} — remove with: launchctl bootout gui/$(id -u)/${LEGACY_LAUNCHD_LABEL}; rm ${plist}`,
      );
    }
  } else if (platform === "linux") {
    const unit = join(homedir(), ".config", "systemd", "user", `${LEGACY_SYSTEMD_UNIT}.service`);
    if (await pathExists(unit)) {
      found.push(
        `systemd unit ${unit} — remove with: systemctl --user disable --now ${LEGACY_SYSTEMD_UNIT}; rm ${unit}; systemctl --user daemon-reload`,
      );
    }
  } else if (platform === "win32") {
    // The task lives in the Task Scheduler store, not on disk, so it can only
    // be probed by querying. A non-zero exit means "not registered".
    const registered = await promisify(execFile)("schtasks", [
      "/Query",
      "/TN",
      LEGACY_WINDOWS_TASK,
    ]).then(
      () => true,
      () => false,
    );
    if (registered) {
      found.push(
        `Scheduled task ${LEGACY_WINDOWS_TASK} — remove with: schtasks /Delete /TN ${LEGACY_WINDOWS_TASK} /F`,
      );
    }
  }

  if (platform !== "win32") {
    // Harmless on its own, but its presence confirms the daemon ran here.
    const socket = join(resolveAgentSyncHome(), "daemon.sock");
    if (await pathExists(socket)) {
      found.push(`Stale IPC socket ${socket} — remove with: rm ${socket}`);
    }
  }

  if (found.length === 0) {
    return { name, status: "pass", detail: "No pre-0.2.0 daemon registration found." };
  }
  // `warn`, not `fail`: the vault is healthy: this is leftover cruft from an
  // older version, and `fail` would set exit code 1 and break CI wrappers.
  return { name, status: "warn", detail: found.join(" | ") };
}

After — wire it in as check 7 (the slot the old daemon check occupied)

    } catch {
      checks.push({
        name: "Credential files in vault",
        status: "warn",
        detail: "Could not scan vault",
      });
    }

    // 7. No OS service left behind by the removed background daemon
    checks.push(await buildLegacyDaemonCheck());

    // Print results

Phase 3 — commit message that fixes the release semantics

Commit Phase 1 + Phase 2 together with a footer that makes release-please
recompute the version and render the removal. Given
bump-minor-pre-major: true, BREAKING CHANGE on a 0.x package bumps
minor → PR #183 regenerates as chore(main): release 0.2.0.

feat(doctor)!: detect orphaned daemon service registrations

The background daemon and auto-sync subsystem were removed in #192 but never
released, so npm's latest (0.1.14) still ships it. Removing the code cannot
unregister a service an older version installed, and it deleted the only
command that could uninstall one.

Adds a doctor check that reports a leftover launchd job, systemd user unit,
Windows scheduled task, or stale IPC socket with the exact removal command.
Surfaces `refactor` in release-please's changelog so a removal this size is
never silent again.

BREAKING CHANGE: the `agentsync daemon` command tree and the `[sync]` config
section are removed. A machine that ran `agentsync daemon install` must remove
the leftover OS service by hand — run `agentsync doctor`, which prints the
exact command for this platform. An existing `[sync]` block in agentsync.toml
needs no edit; the schema strips unknown keys.

Closes #205

Phase 4 — release

1. Merge the PR from Phase 3 into main.
2. Wait for the release-please workflow to regenerate PR
   #183; confirm the title
   becomes chore(main): release 0.2.0 and the body gains a
   ⚠ BREAKING CHANGES section plus a Code Refactoring entry for refactor(daemon): remove the background daemon and auto-sync subsystem #192.
3. Optionally edit CHANGELOG.md on the release branch to strike the two
   now-false feat(daemon) / feat(tui): … daemon staleness lines — they
   describe work that was reverted before it ever shipped. release-please
   honours manual edits to the release PR.
4. Merge chore(main): release 0.2.0 #183. Verify publication:

npm view @chrisleekr/agentsync version          # expect 0.2.0
npm view @chrisleekr/agentsync dist-tags
git merge-base --is-ancestor c8dc086 v0.2.0 && echo "daemon removal is released"

---

Verification checklist

bun run check                                   # typecheck + biome + bun test

# no daemon surface in the built binary
bun run build
./dist/agentsync --help | grep -i daemon        # expect no match
./dist/agentsync daemon                         # expect unknown-command error

# orphan detection, exercised per platform without needing that OS
bun test src/commands/__tests__/doctor.test.ts

New tests to add in src/commands/__tests__/doctor.test.ts, mirroring the
existing buildSkillsDirChecks style:

• darwin + plist present → warn, detail contains launchctl bootout
• darwin + nothing present → pass
• linux + unit present → warn, detail contains systemctl --user disable --now
• win32 + schtasks /Query exits 0 → warn, detail contains schtasks /Delete
• win32 + schtasks /Query rejects → pass (must not throw)
• stale daemon.sock alone under a redirected AGENTSYNC_DIR → warn

Out of scope — do not change

• CHANGELOG.md history (release-please owns it; historical daemon entries are correct for their releases).
• docker/e2e/README.md, docker/e2e/compose.yml — those reference Git's own git daemon transport for scenario 17, unrelated to AgentSync's daemon.
• src/commands/vault.ts:113 and src/commands/__tests__/vault.test.ts:110 — comments documenting that the v1→v2 migration strips the legacy [sync] key. Still accurate.
• Re-adding any agentsync daemon subcommand, even a hidden uninstall. The removal command is printed by doctor; a command tree would partially resurrect what this issue asks to delete.

[chrisleekr]

Starting work on this issue — validate the linked implementation plan against current main, add regression coverage first, then implement the smallest sound release metadata and doctor diagnostics changes before shipping through the full PR/CI/review workflow.

[chrisleekr]

Approved implementation plan

Work type: feature. The daemon removal is already on main; this change adds the missing upgrade diagnostic and release-policy protection.

EARS acceptance criteria

1. C1, Direct: WHEN doctor checks macOS with ~/Library/LaunchAgents/com.agentsync.daemon.plist present, THE SYSTEM SHALL return a warning naming the artifact and an exact launchctl bootout plus file-removal command, without executing cleanup.
2. C2, Direct: WHEN doctor checks Linux with ~/.config/systemd/user/agentsync.service present, THE SYSTEM SHALL return a warning naming the artifact and exact systemctl --user disable --now, file-removal, and daemon-reload guidance, without executing cleanup.
3. C3, Direct: WHEN doctor checks Windows and schtasks /Query /TN AgentSync succeeds, THE SYSTEM SHALL return a warning naming the task and exact schtasks /Delete /TN AgentSync /F guidance; WHEN the query reports it absent, THE SYSTEM SHALL not throw and shall report no legacy task.
4. C4, Direct: WHEN doctor checks a non-Windows host and <resolveAgentSyncHome()>/daemon.sock exists, including under AGENTSYNC_DIR, THE SYSTEM SHALL warn with the resolved path and exact file-removal guidance, without deleting it.
5. C5, Direct: WHEN no legacy artifact is found for the selected platform, THE SYSTEM SHALL return a passing Legacy daemon leftovers result and perform no mutation.
6. C6, Supporting: WHEN the full doctor command runs, THE SYSTEM SHALL include the legacy-daemon row in its stable output; warnings SHALL preserve doctor exit success because leftover compatibility state does not make the vault unhealthy.
7. C7, Supporting: WHEN release-please renders a changelog after configuration, THE SYSTEM SHALL show refactor commits while preserving all other release-please v17.6.0 default changelog section types, headings, order, and visibility.

Files and ordered work

• src/commands/doctor.ts: add one read-only legacy-daemon check with injected platform, home paths, and Windows query executor; compose its row into doctor.
• src/commands/__tests__/doctor.test.ts: deterministic macOS, Linux, Windows, redirected socket, no-artifact, exact-guidance, and non-mutation acceptance coverage.
• docker/e2e/scenarios/13-doctor.sh: require the stable row and prove warning state preserves exit 0 and leaves artifacts intact.
• release-please-config.json: reproduce the pinned v17.6.0 defaults and change only refactor visibility.
• src/commands/__tests__/release-please-config.test.ts: lock the complete default contract and visible-refactor policy.

1. Add failing acceptance/config contract checks without production changes.
2. Observe the targeted RED state.
3. Implement the read-only diagnostic through the narrow injected seams.
4. Configure the full pinned changelog override, preserving every default except refactor visibility.
5. Observe targeted GREEN, run the full suite and doctor E2E, then ship with the breaking footer required by the repository's pre-1.0 release policy.

Start-state proof: bun test src/commands/__tests__/doctor.test.ts src/commands/__tests__/release-please-config.test.ts → expected RED.

Corrections to the earlier proposal

• The historical socket default is ~/.config/agentsync/daemon.sock, resolved through resolveAgentSyncHome(), not ~/.agentsync/daemon.sock.
• A platform parameter alone is unsafe for cross-platform tests because it still probes the real home or executes real schtasks; paths and the query executor will be injected.
• changelog-sections is a full override. The implementation will preserve all pinned v17.6.0 defaults and only unhide refactor, rather than unintentionally exposing other sections or dropping the feature alias.

Out of scope: historical changelog edits, Git's daemon E2E, accurate vault migration comments, and merging/publishing the existing release PR.

[chrisleekr]

Implementation blocked at the mandatory full-suite gate

The scoped #205 work is implemented locally and its direct verification is green:

• Start state: RED, buildLegacyDaemonCheck absent and changelog-sections undefined.
• End state: GREEN, 14 targeted tests passed, 0 failed.
• Runtime: Docker scenario 13-doctor.sh passed and preserved exit 0/non-mutation behavior.
• Phase-A acceptance assertions remain byte-identical to their pre-implementation snapshot.

I am not shipping it because the required full suite is red under the repository's CI-pinned Bun 1.3.14. The unchanged test src/commands/tui/__tests__/machines.test.ts:118 reproducibly leaves lastCopy null:

Expected: "host-a"
Received: undefined
0 pass
1 fail

It fails both in isolation after a 10-second wait and in the full suite. The test, src/commands/tui/tabs/machines.ts, and bunfig.toml are byte-identical to origin/main, so this is independent of #205. I created #207 to track it.

Per the implementation workflow's hard gate, no commit, push, or PR was created while the full suite exits non-zero. The #205 changes remain in the local fix/issue-205 worktree for resumption after #207 is resolved.