kandev 0.54.0 → 0.55.0

package/dist/constants.js

@@ -4,6 +4,10 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DEV_KANDEV_DOTDIR = exports.DATA_DIR = exports.CACHE_DIR = exports.KANDEV_TASKS_DIR = exports.KANDEV_HOME_DIR = exports.KANDEV_DOTDIR = exports.HEALTH_TIMEOUT_MS_DEV = exports.HEALTH_TIMEOUT_MS_RELEASE = exports.RANDOM_PORT_RETRIES = exports.RANDOM_PORT_MAX = exports.RANDOM_PORT_MIN = exports.DEFAULT_AGENTCTL_PORT = exports.DEFAULT_WEB_PORT = exports.DEFAULT_BACKEND_PORT = void 0;
+exports.resolveKandevHomeDir = resolveKandevHomeDir;
+exports.resolveDataDir = resolveDataDir;
+exports.resolveCacheDir = resolveCacheDir;
+exports.resolveDatabasePath = resolveDatabasePath;
 exports.devKandevHome = devKandevHome;
 const node_os_1 = __importDefault(require("node:os"));
 const node_path_1 = __importDefault(require("node:path"));
@@ -29,6 +33,18 @@ exports.KANDEV_TASKS_DIR = node_path_1.default.join(exports.KANDEV_HOME_DIR, "ta
 // Local user cache/data directories for release bundles and DB.
 exports.CACHE_DIR = node_path_1.default.join(exports.KANDEV_HOME_DIR, "bin");
 exports.DATA_DIR = node_path_1.default.join(exports.KANDEV_HOME_DIR, "data");
+function resolveKandevHomeDir(env = process.env) {
+    return env.KANDEV_HOME_DIR?.trim() || exports.KANDEV_HOME_DIR;
+}
+function resolveDataDir(env = process.env) {
+    return node_path_1.default.join(resolveKandevHomeDir(env), "data");
+}
+function resolveCacheDir(env = process.env) {
+    return node_path_1.default.join(resolveKandevHomeDir(env), "bin");
+}
+function resolveDatabasePath(env = process.env) {
+    return env.KANDEV_DATABASE_PATH?.trim() || node_path_1.default.join(resolveDataDir(env), "kandev.db");
+}
 // Dev-mode root: an isolated kandev home inside the repo so that running
 // `make dev` from inside a kandev-spawned task workspace does not touch the
 // user's production state.

package/dist/run.js

@@ -27,8 +27,9 @@ const web_1 = require("./web");
  * the highest semver tag available in the cache.
  */
 function findCachedRelease(platformDir, version) {
+    const rootCacheDir = (0, constants_1.resolveCacheDir)();
     if (version) {
-        const cacheDir = node_path_1.default.join(constants_1.CACHE_DIR, version, platformDir);
+        const cacheDir = node_path_1.default.join(rootCacheDir, version, platformDir);
         const bundleDir = node_path_1.default.join(cacheDir, "kandev");
         const backendBin = node_path_1.default.join(bundleDir, "bin", (0, platform_1.getBinaryName)("kandev"));
         if (node_fs_1.default.existsSync(backendBin)) {
@@ -37,14 +38,14 @@ function findCachedRelease(platformDir, version) {
         return null;
     }
     // No version specified — scan for cached tags and pick the latest.
-    if (!node_fs_1.default.existsSync(constants_1.CACHE_DIR))
+    if (!node_fs_1.default.existsSync(rootCacheDir))
         return null;
-    const entries = node_fs_1.default.readdirSync(constants_1.CACHE_DIR).filter((d) => d.startsWith("v"));
+    const entries = node_fs_1.default.readdirSync(rootCacheDir).filter((d) => d.startsWith("v"));
     if (entries.length === 0)
         return null;
     const sorted = (0, version_1.sortVersionsDesc)(entries);
     for (const tag of sorted) {
-        const cacheDir = node_path_1.default.join(constants_1.CACHE_DIR, tag, platformDir);
+        const cacheDir = node_path_1.default.join(rootCacheDir, tag, platformDir);
         const bundleDir = node_path_1.default.join(cacheDir, "kandev");
         const backendBin = node_path_1.default.join(bundleDir, "bin", (0, platform_1.getBinaryName)("kandev"));
         if (node_fs_1.default.existsSync(backendBin)) {
@@ -59,10 +60,11 @@ function findCachedRelease(platformDir, version) {
  * The previous version is kept as a fallback for offline use.
  */
 function cleanOldReleases(currentTag) {
+    const rootCacheDir = (0, constants_1.resolveCacheDir)();
     try {
-        if (!node_fs_1.default.existsSync(constants_1.CACHE_DIR))
+        if (!node_fs_1.default.existsSync(rootCacheDir))
             return;
-        const entries = node_fs_1.default.readdirSync(constants_1.CACHE_DIR).filter((d) => d.startsWith("v"));
+        const entries = node_fs_1.default.readdirSync(rootCacheDir).filter((d) => d.startsWith("v"));
         if (entries.length <= 2)
             return;
         const sorted = (0, version_1.sortVersionsDesc)(entries);
@@ -70,7 +72,7 @@ function cleanOldReleases(currentTag) {
         const keep = new Set([currentTag, sorted[0], sorted[1]]);
         for (const entry of entries) {
             if (!keep.has(entry)) {
-                node_fs_1.default.rmSync(node_path_1.default.join(constants_1.CACHE_DIR, entry), { recursive: true, force: true });
+                node_fs_1.default.rmSync(node_path_1.default.join(rootCacheDir, entry), { recursive: true, force: true });
             }
         }
     }
@@ -87,7 +89,7 @@ async function downloadRuntimeVersion(runtimeVersion) {
     const release = await (0, github_1.getRelease)(runtimeVersion);
     const tag = release.tag_name;
     const assetName = `kandev-${platformDir}.tar.gz`;
-    const cacheDir = node_path_1.default.join(constants_1.CACHE_DIR, tag, platformDir);
+    const cacheDir = node_path_1.default.join((0, constants_1.resolveCacheDir)(), tag, platformDir);
     const archivePath = await (0, github_1.ensureAsset)(tag, assetName, cacheDir, (downloaded, total) => {
         const percent = total ? Math.round((downloaded / total) * 100) : 0;
         const mb = (downloaded / (1024 * 1024)).toFixed(1);
@@ -114,7 +116,7 @@ async function prepareBundleForLaunch({ runtimeVersion, backendPort, webPort, ve
         else {
             try {
                 tag = await downloadRuntimeVersion(runtimeVersion);
-                const cacheDir = node_path_1.default.join(constants_1.CACHE_DIR, tag, platformDir);
+                const cacheDir = node_path_1.default.join((0, constants_1.resolveCacheDir)(), tag, platformDir);
                 bundleDir = (0, bundle_1.findBundleRoot)(cacheDir);
             }
             catch (err) {
@@ -141,25 +143,33 @@ async function prepareBundleForLaunch({ runtimeVersion, backendPort, webPort, ve
     const backendUrl = `http://localhost:${actualBackendPort}`;
     const showOutput = verbose || debug;
     const logLevel = process.env.KANDEV_LOG_LEVEL?.trim() || (debug ? "debug" : verbose ? "info" : "warn");
-    node_fs_1.default.mkdirSync(constants_1.DATA_DIR, { recursive: true });
-    const dbPath = node_path_1.default.join(constants_1.DATA_DIR, "kandev.db");
+    const dataDir = (0, constants_1.resolveDataDir)();
+    node_fs_1.default.mkdirSync(dataDir, { recursive: true });
+    const dbPath = (0, constants_1.resolveDatabasePath)();
     const backendBin = node_path_1.default.join(bundleDir, "bin", (0, platform_1.getBinaryName)("kandev"));
-    const backendEnv = {
-        ...process.env,
-        KANDEV_SERVER_PORT: String(actualBackendPort),
-        KANDEV_WEB_INTERNAL_URL: `http://localhost:${actualWebPort}`,
-        KANDEV_AGENT_STANDALONE_PORT: String(agentctlPort),
-        KANDEV_DATABASE_PATH: dbPath,
-        KANDEV_LOG_LEVEL: logLevel,
-        ...(debug ? { KANDEV_DEBUG_AGENT_MESSAGES: "true", KANDEV_DEBUG_PPROF_ENABLED: "true" } : {}),
-    };
-    const webEnv = {
-        ...process.env,
-        KANDEV_API_BASE_URL: backendUrl,
-        PORT: String(actualWebPort),
-        HOSTNAME: "127.0.0.1",
-    };
-    webEnv.NODE_ENV = "production";
+    const backendEnv = (0, shared_1.buildBackendEnv)({
+        ports: {
+            backendPort: actualBackendPort,
+            webPort: actualWebPort,
+            agentctlPort,
+            backendUrl,
+        },
+        logLevel,
+        extra: {
+            KANDEV_DATABASE_PATH: dbPath,
+            ...(debug ? { KANDEV_DEBUG_AGENT_MESSAGES: "true", KANDEV_DEBUG_PPROF_ENABLED: "true" } : {}),
+        },
+    });
+    const webEnv = (0, shared_1.buildWebEnv)({
+        ports: {
+            backendPort: actualBackendPort,
+            webPort: actualWebPort,
+            agentctlPort,
+            backendUrl,
+        },
+        production: true,
+        debug,
+    });
     return {
         bundleDir,
         backendBin,

package/dist/service/args.js

@@ -11,6 +11,7 @@ const VALID_ACTIONS = new Set([
     "status",
     "logs",
     "config",
+    "self-update",
 ]);
 function parseServiceArgs(argv) {
     if (argv.length === 0 || argv[0] === "--help" || argv[0] === "-h") {
@@ -39,6 +40,22 @@ function parseServiceArgs(argv) {
             out.follow = true;
             continue;
         }
+        if (arg === "--dry-run") {
+            out.dryRun = true;
+            continue;
+        }
+        if (arg === "--intent") {
+            out.intent = takeValue(argv, i, "--intent");
+            i += 1;
+            continue;
+        }
+        if (arg.startsWith("--intent=")) {
+            const value = arg.slice("--intent=".length);
+            if (value.length === 0)
+                throw new args_1.ParseError("--intent requires a value");
+            out.intent = value;
+            continue;
+        }
         if (arg === "--port") {
             out.port = parsePort(takeValue(argv, i, "--port"), "--port");
             i += 1;
@@ -75,6 +92,15 @@ function validateActionFlags(args) {
     if (args.follow && args.action !== "logs") {
         throw new args_1.ParseError(`--follow only applies to 'kandev service logs', not '${args.action}'`);
     }
+    if (args.dryRun && args.action !== "self-update") {
+        throw new args_1.ParseError(`--dry-run only applies to 'kandev service self-update', not '${args.action}'`);
+    }
+    if (args.intent && args.action !== "self-update") {
+        throw new args_1.ParseError(`--intent only applies to 'kandev service self-update', not '${args.action}'`);
+    }
+    if (args.action === "self-update" && !args.showHelp && !args.intent) {
+        throw new args_1.ParseError("kandev service self-update requires --intent <path>");
+    }
     const installOnly = ["port", "homeDir", "noBootStart"];
     if (args.action !== "install") {
         for (const flag of installOnly) {

package/dist/service/index.js

@@ -6,6 +6,7 @@ const args_1 = require("./args");
 const config_1 = require("./config");
 const linux_1 = require("./linux");
 const macos_1 = require("./macos");
+const self_update_1 = require("./self_update");
 function printServiceHelp() {
     console.log(`kandev service — install kandev as an OS-managed service
 
@@ -51,6 +52,12 @@ async function runServiceCommand(argv) {
         (0, config_1.printServiceConfig)(args);
         return;
     }
+    // Hidden helper entrypoint used by the backend self-update endpoint. It is
+    // intentionally absent from help output.
+    if (args.action === "self-update") {
+        (0, self_update_1.runSelfUpdateCommand)(args);
+        return;
+    }
     switch (process.platform) {
         case "linux":
             return (0, linux_1.runLinuxService)(args);

package/dist/service/launchctl.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.spawnLaunchctl = spawnLaunchctl;
+exports.sleepSync = sleepSync;
+exports.bootoutAndWait = bootoutAndWait;
+exports.bootstrapWithRetry = bootstrapWithRetry;
+exports.reloadService = reloadService;
+const node_child_process_1 = require("node:child_process");
+const BOOTOUT_POLL_INTERVAL_MS = 100;
+const BOOTOUT_POLL_ATTEMPTS = 50; // ~5s ceiling waiting for teardown
+const BOOTSTRAP_MAX_ATTEMPTS = 5;
+const BOOTSTRAP_RETRY_BASE_MS = 300;
+function spawnLaunchctl(args, stdio) {
+    const res = (0, node_child_process_1.spawnSync)("launchctl", args, { stdio });
+    return { status: res.status };
+}
+// Block the current thread for `ms`. The launchctl orchestration runs in the
+// synchronous `service install`/`start`/`restart` paths, so we can't await a
+// timer — Atomics.wait gives a dependency-free blocking sleep.
+function sleepSync(ms) {
+    if (ms <= 0)
+        return;
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+function isLoaded(target, run) {
+    // `launchctl print <target>` exits non-zero once the label is gone.
+    return run(["print", target], "ignore").status === 0;
+}
+/**
+ * Boot out a launchd job and wait until launchd has fully removed it. A no-op
+ * (returns promptly) when the label isn't loaded, so fresh installs aren't
+ * slowed down.
+ */
+function bootoutAndWait(target, deps = {}) {
+    const run = deps.run ?? spawnLaunchctl;
+    const sleep = deps.sleep ?? sleepSync;
+    run(["bootout", target], "ignore");
+    for (let attempt = 0; attempt < BOOTOUT_POLL_ATTEMPTS; attempt += 1) {
+        if (!isLoaded(target, run)) {
+            return;
+        }
+        sleep(BOOTOUT_POLL_INTERVAL_MS);
+    }
+}
+/**
+ * Bootstrap a launchd job, retrying through the transient EIO that launchd
+ * returns while a previous instance of the same label finishes tearing down.
+ * Throws with the last exit code if every attempt fails.
+ */
+function bootstrapWithRetry(domain, plistPath, deps = {}) {
+    const run = deps.run ?? spawnLaunchctl;
+    const sleep = deps.sleep ?? sleepSync;
+    let lastStatus = null;
+    for (let attempt = 1; attempt <= BOOTSTRAP_MAX_ATTEMPTS; attempt += 1) {
+        lastStatus = run(["bootstrap", domain, plistPath], "inherit").status;
+        if (lastStatus === 0) {
+            return;
+        }
+        if (attempt < BOOTSTRAP_MAX_ATTEMPTS) {
+            sleep(BOOTSTRAP_RETRY_BASE_MS * attempt);
+        }
+    }
+    throw new Error(`launchctl bootstrap ${domain} ${plistPath} failed with code ${lastStatus}`);
+}
+/**
+ * Reload a launchd job: fully unload (waiting for teardown) then bootstrap with
+ * retry. This is the safe sequence whenever the target might currently be
+ * running — installs that refresh a live service, and `start`.
+ */
+function reloadService(target, domain, plistPath, deps = {}) {
+    bootoutAndWait(target, deps);
+    bootstrapWithRetry(domain, plistPath, deps);
+}

package/dist/service/linux.js

@@ -9,6 +9,7 @@ const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const health_check_1 = require("./health_check");
 const install_helpers_1 = require("./install_helpers");
+const metadata_1 = require("./metadata");
 const paths_1 = require("./paths");
 const templates_1 = require("./templates");
 function makeCtx(args) {
@@ -45,6 +46,9 @@ async function runLinuxService(args) {
         case "config":
             // Handled by the dispatcher in index.ts before reaching the platform layer.
             throw new Error("unreachable: config action handled in service/index.ts");
+        case "self-update":
+            // Handled by the dispatcher in index.ts before reaching the platform layer.
+            throw new Error("unreachable: self-update action handled in service/index.ts");
         default: {
             const _exhaustive = args.action;
             throw new Error(`unhandled service action: ${_exhaustive}`);
@@ -59,16 +63,30 @@ function installSync(ctx) {
     const launcher = (0, paths_1.captureLauncher)();
     const homeDir = (0, paths_1.resolveHomeDir)(ctx.args.homeDir, ctx.isSystem);
     const logDir = (0, paths_1.resolveLogDir)(homeDir);
+    const metadataPath = (0, metadata_1.serviceMetadataPath)(homeDir);
+    const mode = ctx.isSystem ? "system" : "user";
+    const systemUser = ctx.isSystem ? (0, paths_1.resolveServiceUser)(true) : undefined;
     const unit = (0, templates_1.renderSystemdUnit)({
         launcher,
         homeDir,
         logDir,
         port: ctx.args.port,
-        systemUser: ctx.isSystem ? (0, paths_1.resolveServiceUser)(true) : undefined,
-        mode: ctx.isSystem ? "system" : "user",
+        systemUser,
+        mode,
+        serviceMetadataPath: metadataPath,
     });
     node_fs_1.default.mkdirSync(node_path_1.default.dirname(ctx.unitPath), { recursive: true });
     const outcome = (0, install_helpers_1.writeUnitFile)(ctx.unitPath, unit);
+    (0, metadata_1.writeServiceInstallMetadata)(metadataPath, (0, metadata_1.buildServiceInstallMetadata)({
+        manager: "systemd",
+        mode,
+        launcher,
+        homeDir,
+        logDir,
+        servicePath: ctx.unitPath,
+        port: ctx.args.port,
+        systemUser,
+    }));
     runSystemctl(ctx, ["daemon-reload"]);
     // Always run enable --now so 'install' is fully idempotent: if the user
     // manually disabled or stopped the service, re-running install brings it

package/dist/service/macos.js

@@ -11,6 +11,8 @@ const node_os_1 = __importDefault(require("node:os"));
 const node_path_1 = __importDefault(require("node:path"));
 const health_check_1 = require("./health_check");
 const install_helpers_1 = require("./install_helpers");
+const launchctl_1 = require("./launchctl");
+const metadata_1 = require("./metadata");
 const paths_1 = require("./paths");
 const templates_1 = require("./templates");
 function makeCtx(args) {
@@ -49,6 +51,9 @@ async function runMacosService(args) {
         case "config":
             // Handled by the dispatcher in index.ts before reaching the platform layer.
             throw new Error("unreachable: config action handled in service/index.ts");
+        case "self-update":
+            // Handled by the dispatcher in index.ts before reaching the platform layer.
+            throw new Error("unreachable: self-update action handled in service/index.ts");
         default: {
             const _exhaustive = args.action;
             throw new Error(`unhandled service action: ${_exhaustive}`);
@@ -63,23 +68,41 @@ function installSync(ctx) {
     const launcher = (0, paths_1.captureLauncher)();
     const homeDir = (0, paths_1.resolveHomeDir)(ctx.args.homeDir, ctx.isSystem);
     const logDir = (0, paths_1.resolveLogDir)(homeDir);
+    const metadataPath = (0, metadata_1.serviceMetadataPath)(homeDir);
+    const mode = ctx.isSystem ? "system" : "user";
+    const systemUser = ctx.isSystem ? (0, paths_1.resolveServiceUser)(true) : undefined;
     node_fs_1.default.mkdirSync(logDir, { recursive: true });
     const plist = (0, templates_1.renderLaunchdPlist)({
         launcher,
         homeDir,
         logDir,
         port: ctx.args.port,
-        systemUser: ctx.isSystem ? (0, paths_1.resolveServiceUser)(true) : undefined,
-        mode: ctx.isSystem ? "system" : "user",
+        systemUser,
+        mode,
+        serviceMetadataPath: metadataPath,
     });
     node_fs_1.default.mkdirSync(node_path_1.default.dirname(ctx.plistPath), { recursive: true });
     const outcome = (0, install_helpers_1.writeUnitFile)(ctx.plistPath, plist);
+    (0, metadata_1.writeServiceInstallMetadata)(metadataPath, (0, metadata_1.buildServiceInstallMetadata)({
+        manager: "launchd",
+        mode,
+        launcher,
+        homeDir,
+        logDir,
+        servicePath: ctx.plistPath,
+        port: ctx.args.port,
+        systemUser,
+    }));
     // launchctl bootstrap fails if the label is already loaded — bootout first
     // (ignoring its error if nothing was loaded). This means 'install' is
     // idempotent: re-running it reloads the unit even if the file is unchanged,
     // which is how we recover from a user manually unloading the service.
-    (0, node_child_process_1.spawnSync)("launchctl", ["bootout", ctx.target], { stdio: "ignore" });
-    runLaunchctl(["bootstrap", ctx.domain, ctx.plistPath]);
+    //
+    // `reloadService` waits for bootout's async teardown before bootstrapping and
+    // retries the transient EIO ("Bootstrap failed: 5") that launchd returns while
+    // a still-running instance is torn down — the failure that broke self-update,
+    // where this install runs against a live service. See launchctl.ts.
+    (0, launchctl_1.reloadService)(ctx.target, ctx.domain, ctx.plistPath);
     runLaunchctl(["enable", ctx.target], { allowFailure: true });
     console.log(outcome === "unchanged"
         ? "[kandev] service is loaded and running"
@@ -107,9 +130,9 @@ function uninstall(ctx) {
 // so each begins with a bootout-then-bootstrap dance similar to installSync.
 function startService(ctx) {
     // Idempotent: if the label is already loaded, bootstrap would fail. Bootout
-    // first so start works whether the service was previously running or stopped.
-    (0, node_child_process_1.spawnSync)("launchctl", ["bootout", ctx.target], { stdio: "ignore" });
-    runLaunchctl(["bootstrap", ctx.domain, ctx.plistPath]);
+    // first (waiting for teardown) so start works whether the service was
+    // previously running or stopped.
+    (0, launchctl_1.reloadService)(ctx.target, ctx.domain, ctx.plistPath);
 }
 function stopService(ctx) {
     runLaunchctl(["bootout", ctx.target], { allowFailure: true });
@@ -121,7 +144,9 @@ function restartService(ctx) {
     const res = (0, node_child_process_1.spawnSync)("launchctl", ["kickstart", "-k", ctx.target], { stdio: "inherit" });
     if (res.status === 0)
         return;
-    runLaunchctl(["bootstrap", ctx.domain, ctx.plistPath]);
+    // kickstart fails when the job isn't loaded — reload it (waiting for any
+    // residual teardown and retrying the transient bootstrap EIO).
+    (0, launchctl_1.reloadService)(ctx.target, ctx.domain, ctx.plistPath);
 }
 function showStatus(ctx) {
     const res = (0, node_child_process_1.spawnSync)("launchctl", ["print", ctx.target], {

package/dist/service/metadata.js

@@ -0,0 +1,46 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.serviceMetadataPath = serviceMetadataPath;
+exports.buildServiceInstallMetadata = buildServiceInstallMetadata;
+exports.writeServiceInstallMetadata = writeServiceInstallMetadata;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+function serviceMetadataPath(homeDir) {
+    return node_path_1.default.join(homeDir, "service", "install.json");
+}
+function buildServiceInstallMetadata(input) {
+    const out = {
+        version: 1,
+        manager: input.manager,
+        mode: input.mode,
+        kind: input.launcher.kind,
+        home_dir: input.homeDir,
+        log_dir: input.logDir,
+        service_path: input.servicePath,
+        node_path: input.launcher.nodePath,
+        cli_entry: input.launcher.cliEntry,
+        installed_at: (input.now ?? new Date()).toISOString(),
+    };
+    if (input.launcher.bundleDir)
+        out.bundle_dir = input.launcher.bundleDir;
+    if (input.launcher.version)
+        out.launcher_version = input.launcher.version;
+    if (input.port !== undefined)
+        out.port = input.port;
+    if (input.systemUser)
+        out.system_user = input.systemUser;
+    return out;
+}
+function writeServiceInstallMetadata(metadataPath, metadata) {
+    const dir = node_path_1.default.dirname(metadataPath);
+    // `mode` on mkdir/writeFile only applies when the path is created. chmod after
+    // so a pre-existing service dir / install.json is tightened to owner-only too
+    // (it can hold launcher paths and the metadata that gates self-update).
+    node_fs_1.default.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    node_fs_1.default.chmodSync(dir, 0o700);
+    node_fs_1.default.writeFileSync(metadataPath, `${JSON.stringify(metadata, null, 2)}\n`, { mode: 0o600 });
+    node_fs_1.default.chmodSync(metadataPath, 0o600);
+}

package/dist/service/paths.js

@@ -75,8 +75,8 @@ function homebrewShimPath(cliEntry) {
  *
  * The unit file hard-codes absolute paths because systemd/launchd start with an
  * empty PATH and may not see the user's `node` or `kandev` shim. By recording
- * `process.execPath` (node) and `process.argv[1]` (cli.js) at install time we
- * avoid any PATH lookups at service-run time.
+ * `process.execPath` (node) and the resolved CLI entry at install time we avoid
+ * any PATH lookups at service-run time.
  */
 function captureLauncher() {
     const nodePath = process.execPath;
@@ -85,9 +85,11 @@ function captureLauncher() {
     const version = process.env.KANDEV_VERSION;
     const kind = bundleDir
         ? "homebrew"
-        : cliEntry.includes(`${node_path_1.default.sep}node_modules${node_path_1.default.sep}`)
-            ? "npm"
-            : "unknown";
+        : looksLikeNpxEntry(cliEntry)
+            ? "npx"
+            : cliEntry.includes(`${node_path_1.default.sep}node_modules${node_path_1.default.sep}`)
+                ? "npm"
+                : "unknown";
     // For Homebrew installs, prefer the floating bin shim so the unit survives
     // `brew upgrade` (which deletes the versioned Cellar dir baked into nodePath
     // /cliEntry). Only adopt it when the shim actually exists on disk; otherwise
@@ -100,10 +102,13 @@ function captureLauncher() {
     }
     return { nodePath, cliEntry, kind, bundleDir, version, shimPath };
 }
+function looksLikeNpxEntry(cliEntry) {
+    return cliEntry.includes(`${node_path_1.default.sep}_npx${node_path_1.default.sep}`);
+}
 function resolveCliEntry() {
     const argvEntry = process.argv[1];
     if (argvEntry && node_fs_1.default.existsSync(argvEntry)) {
-        return node_path_1.default.resolve(argvEntry);
+        return node_path_1.default.resolve(node_fs_1.default.realpathSync(argvEntry));
     }
     throw new Error("could not resolve the kandev CLI entry path from process.argv[1]; " +
         "rerun via the kandev binary");

package/dist/service/self_update.js

@@ -0,0 +1,223 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readSelfUpdateIntent = readSelfUpdateIntent;
+exports.planSelfUpdate = planSelfUpdate;
+exports.runSelfUpdateCommand = runSelfUpdateCommand;
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_os_1 = __importDefault(require("node:os"));
+const node_path_1 = __importDefault(require("node:path"));
+const paths_1 = require("./paths");
+function readSelfUpdateIntent(intentPath) {
+    return JSON.parse(node_fs_1.default.readFileSync(intentPath, "utf8"));
+}
+function planSelfUpdate(intent, opts = {}) {
+    const platform = opts.platform ?? process.platform;
+    const target = npmVersion(intent.target_version || intent.target_tag);
+    const install = intent.install;
+    const installArgs = serviceInstallArgs(install);
+    const commands = [];
+    if (install.kind === "homebrew") {
+        // `brew upgrade` installs the tap formula's current version; it can't be
+        // pinned to intent.target_version the way npm/npx can (Homebrew has no
+        // stable "install version X" without a separate versioned formula). In
+        // practice both target_version and the formula derive from the same latest
+        // GitHub release, so they match. If the formula lags, the restarted backend
+        // reports the older version and the frontend progress poll (which waits for
+        // info.version === target_version) times out gracefully rather than
+        // reporting a false success.
+        commands.push({ command: "brew", args: ["upgrade", "kandev"] });
+        // Re-run service install via the upgraded `kandev` wrapper (resolved on
+        // PATH), NOT `node <cli_entry>`. Homebrew installs into version-pinned
+        // Cellar dirs, so the recorded cli_entry still points at the OLD bundle
+        // after `brew upgrade`; worse, invoking node on it directly runs without
+        // KANDEV_BUNDLE_DIR/KANDEV_VERSION, so the install is mis-detected as
+        // kind "unknown" and the regenerated unit loses the bundle env — the
+        // restarted backend then can't find its runtime and the service stays down.
+        // The wrapper is version-stable and re-sets the bundle env. (Mirrors the
+        // manual `kandev service install` we already document for Homebrew.)
+        commands.push({ command: "kandev", args: installArgs });
+    }
+    else if (install.kind === "npm") {
+        commands.push({ command: "npm", args: npmInstallArgs(install.cli_entry, target) });
+        commands.push({ command: install.node_path, args: [install.cli_entry, ...installArgs] });
+    }
+    else if (install.kind === "npx") {
+        commands.push({ command: "npx", args: ["-y", `kandev@${target}`, ...installArgs] });
+    }
+    else {
+        throw new Error(`unsupported install kind "${install.kind}"`);
+    }
+    commands.push(restartCommand(install, platform, opts.uid));
+    return commands;
+}
+function runSelfUpdateCommand(args, runner = spawnCommand) {
+    if (!args.intent) {
+        throw new Error("kandev service self-update requires --intent <path>");
+    }
+    const intent = readSelfUpdateIntent(args.intent);
+    const commands = planSelfUpdate(intent);
+    if (args.dryRun || process.env.KANDEV_E2E_MOCK === "true") {
+        console.log(JSON.stringify({
+            dry_run: !!args.dryRun,
+            fake: process.env.KANDEV_E2E_MOCK === "true",
+            target_version: intent.target_version,
+            commands,
+        }, null, 2));
+        return;
+    }
+    const log = openSelfUpdateLog(intent);
+    try {
+        log?.line(`self-update target ${intent.target_tag} (${intent.target_version})`);
+        log?.line(`install kind=${intent.install.kind} manager=${intent.install.manager}`);
+        log?.line(`planned ${commands.length} command(s):`);
+        commands.forEach((step, i) => log?.line(`  [${i + 1}/${commands.length}] ${formatCommand(step)}`));
+        runSelfUpdateSteps(commands, runner, log);
+        log?.line("self-update completed successfully");
+    }
+    finally {
+        log?.close();
+    }
+}
+function runSelfUpdateSteps(commands, runner, log) {
+    for (const [i, step] of commands.entries()) {
+        log?.line(`\n[${i + 1}/${commands.length}] $ ${formatCommand(step)}`);
+        const res = runner(step.command, step.args);
+        teeCommandOutput(log, res);
+        if (res.error) {
+            log?.line(`! spawn error: ${res.error.message}`);
+            throw res.error;
+        }
+        if (res.status !== 0) {
+            log?.line(`! exited with code ${res.status}`);
+            throw new Error(`${formatCommand(step)} failed with code ${res.status}`);
+        }
+        log?.line("  exit 0");
+    }
+}
+function formatCommand(step) {
+    return [step.command, ...step.args].join(" ");
+}
+function serviceInstallArgs(install) {
+    const args = ["service", "install"];
+    if (install.mode === "system")
+        args.push("--system");
+    args.push("--home-dir", install.home_dir);
+    if (install.port !== undefined) {
+        args.push("--port", String(install.port));
+    }
+    return args;
+}
+function npmInstallArgs(cliEntry, target) {
+    const args = ["install", "-g"];
+    const prefix = npmPrefixFromCliEntry(cliEntry);
+    if (prefix) {
+        args.push("--prefix", prefix);
+    }
+    args.push(`kandev@${target}`);
+    return args;
+}
+function npmPrefixFromCliEntry(cliEntry) {
+    const marker = `${node_path_1.default.sep}lib${node_path_1.default.sep}node_modules${node_path_1.default.sep}kandev${node_path_1.default.sep}`;
+    const index = cliEntry.indexOf(marker);
+    if (index < 0) {
+        return undefined;
+    }
+    return index === 0 ? node_path_1.default.sep : cliEntry.slice(0, index);
+}
+function restartCommand(install, platform, uid) {
+    if (platform === "linux") {
+        return install.mode === "system"
+            ? { command: "systemctl", args: ["restart", paths_1.SERVICE_NAME] }
+            : { command: "systemctl", args: ["--user", "restart", paths_1.SERVICE_NAME] };
+    }
+    if (platform === "darwin") {
+        // Resolve the uid lazily inside the darwin branch — Linux never needs it, so
+        // os.userInfo() shouldn't run there.
+        const resolvedUid = uid ?? node_os_1.default.userInfo().uid;
+        const domain = install.mode === "system" ? "system" : `gui/${resolvedUid}`;
+        return { command: "launchctl", args: ["kickstart", "-k", `${domain}/${paths_1.LAUNCHD_LABEL}`] };
+    }
+    throw new Error(`unsupported platform "${platform}"`);
+}
+function npmVersion(versionOrTag) {
+    const stripped = versionOrTag.replace(/^v/, "");
+    return stripped || "latest";
+}
+function spawnCommand(command, args) {
+    // Capture stdout/stderr (rather than inheriting) so the self-update log can
+    // tee each step's output. The helper runs detached under launchd/systemd, so
+    // its console output would otherwise go nowhere visible — the log file is the
+    // only forensic trail when an update fails mid-flight. maxBuffer is bumped
+    // well above the 1 MiB default because `npm install -g` is chatty.
+    return (0, node_child_process_1.spawnSync)(command, args, { maxBuffer: 64 * 1024 * 1024 });
+}
+/**
+ * Open a timestamped log file under the service's log dir for this self-update
+ * run. The helper is spawned outside the service process (so a restart doesn't
+ * kill it mid-update), which means it has no service log of its own — without
+ * this file a failed update on macOS/launchd is nearly invisible. Best-effort:
+ * if the log dir can't be created we return null and the update still runs.
+ */
+function openSelfUpdateLog(intent) {
+    const dir = intent.install.log_dir || logDirFromHome(intent.install.home_dir);
+    if (!dir) {
+        return null;
+    }
+    try {
+        node_fs_1.default.mkdirSync(dir, { recursive: true });
+        // Self-update logs can contain install paths/env; keep the dir owner-only
+        // even if it pre-existed with looser perms.
+        node_fs_1.default.chmodSync(dir, 0o700);
+        const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+        const filePath = node_path_1.default.join(dir, `self-update-${stamp}.log`);
+        const fd = node_fs_1.default.openSync(filePath, "a");
+        const write = (chunk) => {
+            try {
+                // The `Buffer | string` union matches neither writeSync overload
+                // directly; the cast picks one — both write the runtime value correctly.
+                node_fs_1.default.writeSync(fd, chunk);
+            }
+            catch {
+                // A write failure mid-update must not abort the update itself.
+            }
+        };
+        process.stdout.write(`[kandev] self-update log: ${filePath}\n`);
+        write(`# kandev self-update ${new Date().toISOString()}\n`);
+        return {
+            path: filePath,
+            line: (message) => write(`${message}\n`),
+            raw: (chunk) => write(chunk),
+            close: () => {
+                try {
+                    node_fs_1.default.closeSync(fd);
+                }
+                catch {
+                    // already closed / never opened
+                }
+            },
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function logDirFromHome(homeDir) {
+    return homeDir ? node_path_1.default.join(homeDir, "logs") : "";
+}
+// Mirror a command's captured output to both the helper log and the process's
+// own stdout/stderr, so whatever does manage to capture the helper's streams
+// (e.g. launchd's StandardOut/ErrorPath, systemd's journal) still sees it.
+function teeCommandOutput(log, res) {
+    if (res.stdout && res.stdout.length) {
+        process.stdout.write(res.stdout);
+        log?.raw(res.stdout);
+    }
+    if (res.stderr && res.stderr.length) {
+        process.stderr.write(res.stderr);
+        log?.raw(res.stderr);
+    }
+}

package/dist/service/templates.js

@@ -82,6 +82,9 @@ function renderSystemdUnit(input) {
     if (!shimPath && input.launcher.version) {
         env.push(envLine("KANDEV_VERSION", input.launcher.version));
     }
+    if (input.serviceMetadataPath) {
+        env.push(...serviceEnvLines(input, "systemd"));
+    }
     const wantedBy = input.mode === "system" ? "multi-user.target" : "default.target";
     const userLine = input.mode === "system" && input.systemUser ? `User=${input.systemUser}\n` : "";
     const exec = shimPath
@@ -133,6 +136,9 @@ function renderLaunchdPlist(input) {
     if (!shimPath && input.launcher.version) {
         envEntries.push(["KANDEV_VERSION", input.launcher.version]);
     }
+    if (input.serviceMetadataPath) {
+        envEntries.push(...serviceEnvEntries(input, "launchd"));
+    }
     const envXml = envEntries
         .map(([k, v]) => `      <key>${escapeXml(k)}</key>\n      <string>${escapeXml(v)}</string>`)
         .join("\n");
@@ -205,3 +211,17 @@ function envLine(key, value) {
     const escaped = value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
     return `Environment="${key}=${escaped}"`;
 }
+function serviceEnvLines(input, manager) {
+    return serviceEnvEntries(input, manager).map(([key, value]) => envLine(key, value));
+}
+function serviceEnvEntries(input, manager) {
+    if (!input.serviceMetadataPath)
+        return [];
+    return [
+        ["KANDEV_RUNNING_AS_SERVICE", "true"],
+        ["KANDEV_SERVICE_MODE", input.mode],
+        ["KANDEV_SERVICE_MANAGER", manager],
+        ["KANDEV_INSTALL_KIND", input.launcher.kind],
+        ["KANDEV_SERVICE_METADATA", input.serviceMetadataPath],
+    ];
+}

package/dist/shared.js

@@ -97,6 +97,7 @@ function buildWebEnv(options) {
             env.NEXT_ALLOWED_DEV_ORIGINS = merged;
     }
     if (debug) {
+        env.KANDEV_DEBUG = "true";
         env.NEXT_PUBLIC_KANDEV_DEBUG = "true";
     }
     return env;

package/dist/start.js

@@ -126,7 +126,11 @@ async function runStart({ repoRoot, backendPort, webPort, verbose = false, debug
     }
     // Production mode: use warn log level for clean output unless verbose/debug
     const showOutput = verbose || debug;
-    const dbPath = process.env.KANDEV_DATABASE_PATH || node_path_1.default.join(constants_1.DATA_DIR, "kandev.db");
+    node_fs_1.default.mkdirSync((0, constants_1.resolveDataDir)(), { recursive: true });
+    // The data dir holds the SQLite DB; keep it owner-only even if it pre-existed
+    // with a looser umask-derived mode.
+    node_fs_1.default.chmodSync((0, constants_1.resolveDataDir)(), 0o700);
+    const dbPath = (0, constants_1.resolveDatabasePath)();
     const logLevel = process.env.KANDEV_LOG_LEVEL?.trim() || (debug ? "debug" : verbose ? "info" : "warn");
     const backendEnv = (0, shared_1.buildBackendEnv)({
         ports,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kandev",
-  "version": "0.54.0",
+  "version": "0.55.0",
   "private": false,
   "description": "Launcher for Kandev — manage tasks, orchestrate agents, review changes, and ship value",
   "license": "AGPL-3.0-only",
@@ -22,11 +22,11 @@
     "npm": ">=7"
   },
   "optionalDependencies": {
-    "@kdlbs/runtime-linux-x64": "0.54.0",
-    "@kdlbs/runtime-linux-arm64": "0.54.0",
-    "@kdlbs/runtime-darwin-x64": "0.54.0",
-    "@kdlbs/runtime-darwin-arm64": "0.54.0",
-    "@kdlbs/runtime-win32-x64": "0.54.0"
+    "@kdlbs/runtime-linux-x64": "0.55.0",
+    "@kdlbs/runtime-linux-arm64": "0.55.0",
+    "@kdlbs/runtime-darwin-x64": "0.55.0",
+    "@kdlbs/runtime-darwin-arm64": "0.55.0",
+    "@kdlbs/runtime-win32-x64": "0.55.0"
   },
   "dependencies": {
     "tar": "^7.5.11",