@camstack/system 1.2.58 → 1.2.59

package/dist/kernel/addon-installer.d.ts

@@ -66,6 +66,37 @@ export interface BackupSweepResult {
     /** Backup dirs deliberately retained (rollback target / last copy). */
     readonly kept: readonly string[];
 }
+/**
+ * A staging tree younger than this may belong to an install still running —
+ * possibly in another process. Only older trees are residue worth sweeping.
+ * Generous on purpose: an addon's runtime-dependency `npm install` on a slow
+ * host is minutes, and the cost of leaving residue one deploy longer is disk,
+ * while the cost of sweeping a live one is a FAILED deploy.
+ */
+export declare const STAGING_RESIDUE_MIN_AGE_MS: number;
+export interface StagingEntryAge {
+    readonly name: string;
+    /** Age of the entry's mtime, in ms. */
+    readonly ageMs: number;
+}
+/**
+ * Pick the staging entries that are safe to delete.
+ *
+ * `installFromTgz` used to clear the WHOLE `.staging` root before creating its
+ * own dir. Two deploys arriving within one install's lifetime — the normal case
+ * when the hub propagates two packages back to back — meant the second one
+ * deleted the first one's tree out from under its running `npm install`:
+ *
+ *   npm error code ENOENT
+ *   npm error path …/.staging/install-14820-2026-08-07T12-28-28-875Z/package/package.json
+ *
+ * which the propagation then reported as `runtime dependency install failed`.
+ * Observed on the Mac desktop agent and on little-unraid on 2026-08-07.
+ *
+ * So a sweep only removes what cannot be live: not a tree this process is
+ * building, and not one young enough to belong to anybody's in-flight install.
+ */
+export declare function selectSweepableStaging(entries: readonly StagingEntryAge[], inFlight: ReadonlySet<string>, minAgeMs?: number): readonly string[];
 export declare class AddonInstaller {
     readonly addonsDir: string;
     private readonly registry;
@@ -82,6 +113,11 @@ export declare class AddonInstaller {
      * `getAddonInstallSource`).
      */
     readonly manifest: AddonManifest;
+    /**
+     * Basenames under `.staging` this process is currently building. Never swept
+     * — see {@link selectSweepableStaging}.
+     */
+    private readonly inFlightStaging;
     constructor(config: AddonInstallerConfig, logger?: IScopedLogger);
     /**
      * Where a bootstrapped npm lives when the host has none on PATH (packaged
@@ -154,14 +190,17 @@ export declare class AddonInstaller {
      */
     ensureRequiredPackages(packages?: readonly string[]): Promise<void>;
     /**
-     * Reconcile the install manifest with the addons actually present on
-     * disk. Seeded addons (baked into the image and copied verbatim by the
-     * container entrypoint) never pass through an `install*` codepath, so
-     * they are missing from `manifest.json` and `applyUpdate` would reject
-     * them with "not currently tracked in manifest". Call this once after
-     * `ensureRequiredPackages` so every on-disk addon is updatable.
+     * Reconcile the install manifest against the addons actually present on
+     * disk: register seeded addons, correct a version that disagrees with the
+     * installed `package.json`, and drop entries naming a directory that does
+     * not exist. Call once after `ensureRequiredPackages`, before any update
+     * can be in flight. See `AddonManifest.reconcileFromDisk` for the rules.
+     *
+     * Every correction is logged by name — a manifest that silently disagreed
+     * with disk is what made "@camstack/system 1.2.29" read as installed on a
+     * hub that deliberately has no copy of it.
      *
-     * Returns the number of manifest entries added.
+     * Returns the number of changes.
      */
     reconcileManifest(): number;
     /**
@@ -252,6 +291,15 @@ export declare class AddonInstaller {
      * on the next deploy.
      */
     private evictInstallDir;
+    /**
+     * Best-effort removal of `.staging` residue left by a CRASHED earlier deploy.
+     *
+     * Deliberately not `sweepGraveyard`: an evicted `.evicting/*` dir is dead by
+     * construction, but a `.staging/*` dir may be an install still running — in
+     * this process or another one. Deleting one of those fails a live deploy with
+     * an ENOENT on its own package.json, which is what happened on 2026-08-07.
+     */
+    private sweepStagingResidue;
     /** Best-effort removal of leftover `.evicting/*` dirs from earlier deploys. */
     private sweepGraveyard;
     /** Install addon from a tgz file (uploaded or downloaded) */

package/dist/kernel/addon-manifest.d.ts

@@ -23,6 +23,15 @@ export interface AddonManifestEntry {
      */
     meta?: Record<string, unknown>;
 }
+/** One correction `reconcileFromDisk` made to bring the manifest back to disk truth. */
+export interface ManifestReconcileChange {
+    readonly kind: 'added' | 'version-corrected' | 'pruned';
+    readonly name: string;
+    /** Version the manifest claimed before the change. Absent for `added`. */
+    readonly from?: string;
+    /** Version now recorded. Absent for `pruned`. */
+    readonly to?: string;
+}
 export interface AddonManifestFile {
     /**
      * Schema version. Increment whenever the on-disk shape changes
@@ -67,26 +76,37 @@ export declare class AddonManifest {
      */
     invalidate(): void;
     /**
-     * Reconcile the manifest with what is actually present on disk.
+     * Reconcile the manifest against what is actually present on disk.
      *
-     * For every `@scope/<pkg>` directory under `addonsDir` that has a
-     * readable `package.json` but NO manifest entry yet, add one with
-     * source `'seed'`. Existing entries are left untouched (their source,
-     * version and timestamps are authoritative — a later install/update
-     * overwrites them through `upsert`).
+     * **The directory is the truth.** It is what `AddonLoader` runs; a manifest
+     * that disagrees with it is a lie the update flow and the admin UI then
+     * repeat. Three corrections, all idempotent and safe on every boot:
      *
-     * Why this exists: addons baked into the Docker/Electron image are
-     * copied straight into `addonsDir` by the container entrypoint (the
-     * launcher's `ensureRequiredPackages` then sees `package.json` already
-     * present and skips, never calling `upsert`). Without this reconcile
-     * those seeded addons stay absent from the manifest, so `applyUpdate`
-     * rejects them with "not currently tracked in manifest" — which is
-     * exactly what broke "Update all" on a fresh image. Idempotent and
-     * safe to run on every boot.
+     *  - **added** — an on-disk addon with no entry gets one, source `'seed'`.
+     *    Addons baked into the Docker/Electron image are copied straight into
+     *    `addonsDir` by the container entrypoint (`ensureRequiredPackages` then
+     *    sees `package.json` present and skips, never calling `upsert`), so they
+     *    would otherwise stay untracked and `applyUpdate` would reject them with
+     *    "not currently tracked in manifest" — what broke "Update all" on a
+     *    fresh image.
+     *  - **version-corrected** — an entry whose version disagrees with the
+     *    installed `package.json` adopts the DISK version. Provenance (`source`,
+     *    `installedAt`) is NOT derivable from disk and stays authoritative here;
+     *    `updatedAt` is left alone because the correction is not an update, and
+     *    stamping `now` would claim an install that never happened.
+     *  - **pruned** — an entry naming a directory that does not exist. The live
+     *    hub carried three (`@camstack/system 1.2.29`, `addon-viewer-ui 1.1.39`,
+     *    `addon-agent-ui 1.2.4`); `@camstack/system` in particular is
+     *    host-provided and deliberately NOT seeded under `addonsDir`
+     *    ([D45]), so its entry advertised a copy that must not exist.
+     *    An entry holding a `lastBackupDir` is NEVER pruned: that pointer is the
+     *    only reference to a pre-update backup, and the launcher's backup sweep
+     *    reclaims anything the manifest does not point at.
      *
-     * Returns the number of entries added.
+     * `onChange` receives one record per correction, so the caller can log
+     * exactly what moved. Returns the total number of changes.
      */
-    reconcileFromDisk(addonsDir: string): number;
+    reconcileFromDisk(addonsDir: string, onChange?: (change: ManifestReconcileChange) => void): number;
     /**
      * Migration helper: if the manifest is empty but the addons directory
      * has packages with `.install-source` markers (the legacy per-addon

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/system",
-  "version": "1.2.58",
+  "version": "1.2.59",
   "description": "Core addon for CamStack — builtins, pipeline, process management, auth, logging, events",
   "keywords": [
     "camstack",