instar 1.3.1594 → 1.3.1595

package/dist/core/DesktopHelperPermissionNotice.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Tells the operator, once, that a Mac's desktop helper needs its macOS
+ * permission again. Without this the machine only reads "not ready", and only
+ * to someone who looks. Signal only: it never grants, blocks or restarts.
+ */
+import type { DesktopProbe } from './DesktopHost.js';
+export interface DesktopHelperPermissionNoticeDeps {
+    machineLabel: string;
+    machineId: string;
+    probe(): Promise<DesktopProbe & {
+        ready: boolean;
+    }>;
+    sourceHash(): string | null;
+    /** True for the first agent on this Mac to raise this notice. */
+    claim(): boolean;
+    /** Gives the notice back so a later check, or a sibling agent, can raise it. */
+    release(): void;
+    raise(item: {
+        id: string;
+        conditionKey: string;
+        title: string;
+        body: string;
+    }): Promise<unknown>;
+    clear(conditionKey: string, resolution: string): void;
+}
+export declare class DesktopHelperPermissionNotice {
+    private readonly deps;
+    private timer;
+    private raisedKey;
+    private running;
+    constructor(deps: DesktopHelperPermissionNoticeDeps);
+    start(): void;
+    stop(): void;
+    /** One check. Public so tests drive it without a clock. */
+    check(): Promise<void>;
+    private tick;
+}
+//# sourceMappingURL=DesktopHelperPermissionNotice.d.ts.map

package/dist/core/DesktopHelperPermissionNotice.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DesktopHelperPermissionNotice.d.ts","sourceRoot":"","sources":["../../src/core/DesktopHelperPermissionNotice.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAMrD,MAAM,WAAW,iCAAiC;IAChD,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,IAAI,OAAO,CAAC,YAAY,GAAG;QAAE,KAAK,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IACpD,UAAU,IAAI,MAAM,GAAG,IAAI,CAAC;IAC5B,iEAAiE;IACjE,KAAK,IAAI,OAAO,CAAC;IACjB,gFAAgF;IAChF,OAAO,IAAI,IAAI,CAAC;IAChB,KAAK,CAAC,IAAI,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACjG,KAAK,CAAC,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CACvD;AAED,qBAAa,6BAA6B;IAK5B,OAAO,CAAC,QAAQ,CAAC,IAAI;IAJjC,OAAO,CAAC,KAAK,CAA8C;IAC3D,OAAO,CAAC,SAAS,CAAuB;IACxC,OAAO,CAAC,OAAO,CAAS;IAExB,YAA6B,IAAI,EAAE,iCAAiC,EAAI;IAExE,KAAK,IAAI,IAAI,CAGZ;IAED,IAAI,IAAI,IAAI,CAGX;IAED,2DAA2D;IACrD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAuB3B;YAEa,IAAI;CAYnB"}

package/dist/core/DesktopHelperPermissionNotice.js

@@ -0,0 +1,65 @@
+import { desktopProbeUnavailableReason } from './DesktopProbeReadiness.js';
+const FIRST_CHECK_MS = 60_000;
+const RECHECK_MS = 15 * 60_000;
+export class DesktopHelperPermissionNotice {
+    deps;
+    timer = null;
+    raisedKey = null;
+    running = false;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    start() {
+        this.timer = setTimeout(() => void this.tick(), FIRST_CHECK_MS);
+        this.timer.unref?.();
+    }
+    stop() {
+        if (this.timer)
+            clearTimeout(this.timer);
+        this.timer = null;
+    }
+    /** One check. Public so tests drive it without a clock. */
+    async check() {
+        const probe = await this.deps.probe();
+        const hash = this.deps.sourceHash();
+        if (!hash)
+            return;
+        const conditionKey = `desktop-helper-permission:${this.deps.machineId}:${hash.slice(0, 16)}`;
+        if (probe.screenPermission && probe.inputPermission) {
+            // Unconditional: the item outlives this process, and closing none is a no-op.
+            this.deps.clear(conditionKey, 'macOS permission is back for this helper');
+            this.raisedKey = null;
+            return;
+        }
+        if (!probe.helperChange || this.raisedKey === conditionKey || !this.deps.claim())
+            return;
+        try {
+            await this.deps.raise({
+                id: conditionKey, conditionKey,
+                title: `${this.deps.machineLabel}: Remote Desktop needs its Mac permission again`,
+                body: desktopProbeUnavailableReason(probe),
+            });
+        }
+        catch (error) {
+            this.deps.release();
+            throw error;
+        }
+        this.raisedKey = conditionKey;
+    }
+    async tick() {
+        if (this.running)
+            return;
+        this.running = true;
+        try {
+            await this.check();
+        }
+        catch { // @silent-fallback-ok — a failed check repeats at the next tick; the helper reason stays on /desktop/diagnostics.
+        }
+        finally {
+            this.running = false;
+            this.timer = setTimeout(() => void this.tick(), RECHECK_MS);
+            this.timer.unref?.();
+        }
+    }
+}
+//# sourceMappingURL=DesktopHelperPermissionNotice.js.map

package/dist/core/DesktopHelperPermissionNotice.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DesktopHelperPermissionNotice.js","sourceRoot":"","sources":["../../src/core/DesktopHelperPermissionNotice.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,6BAA6B,EAAE,MAAM,4BAA4B,CAAC;AAE3E,MAAM,cAAc,GAAG,MAAM,CAAC;AAC9B,MAAM,UAAU,GAAG,EAAE,GAAG,MAAM,CAAC;AAe/B,MAAM,OAAO,6BAA6B;IAKX,IAAI;IAJzB,KAAK,GAAyC,IAAI,CAAC;IACnD,SAAS,GAAkB,IAAI,CAAC;IAChC,OAAO,GAAG,KAAK,CAAC;IAExB,YAA6B,IAAuC;oBAAvC,IAAI;IAAsC,CAAC;IAExE,KAAK;QACH,IAAI,CAAC,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,KAAK,IAAI,CAAC,IAAI,EAAE,EAAE,cAAc,CAAC,CAAC;QAChE,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,EAAE,CAAC;IACvB,CAAC;IAED,IAAI;QACF,IAAI,IAAI,CAAC,KAAK;YAAE,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACzC,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;IACpB,CAAC;IAED,2DAA2D;IAC3D,KAAK,CAAC,KAAK;QACT,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC;QACtC,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,CAAC;QACpC,IAAI,CAAC,IAAI;YAAE,OAAO;QAClB,MAAM,YAAY,GAAG,6BAA6B,IAAI,CAAC,IAAI,CAAC,SAAS,IAAI,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC;QAC7F,IAAI,KAAK,CAAC,gBAAgB,IAAI,KAAK,CAAC,eAAe,EAAE,CAAC;YACpD,8EAA8E;YAC9E,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,YAAY,EAAE,0CAA0C,CAAC,CAAC;YAC1E,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;YACtB,OAAO;QACT,CAAC;QACD,IAAI,CAAC,KAAK,CAAC,YAAY,IAAI,IAAI,CAAC,SAAS,KAAK,YAAY,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE;YAAE,OAAO;QACzF,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC;gBACpB,EAAE,EAAE,YAAY,EAAE,YAAY;gBAC9B,KAAK,EAAE,GAAG,IAAI,CAAC,IAAI,CAAC,YAAY,iDAAiD;gBACjF,IAAI,EAAE,6BAA6B,CAAC,KAAK,CAAC;aAC3C,CAAC,CAAC;QACL,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;YACpB,MAAM,KAAK,CAAC;QACd,CAAC;QACD,IAAI,CAAC,SAAS,GAAG,YAAY,CAAC;IAChC,CAAC;IAEO,KAAK,CAAC,IAAI;QAChB,IAAI,IAAI,CAAC,OAAO;YAAE,OAAO;QACzB,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;QACpB,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,KAAK,EAAE,CAAC;QACrB,CAAC;QAAC,MAAM,CAAC,CAAC,kHAAkH;QAC5H,CAAC;gBAAS,CAAC;YACT,IAAI,CAAC,OAAO,GAAG,KAAK,CAAC;YACrB,IAAI,CAAC,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,KAAK,IAAI,CAAC,IAAI,EAAE,EAAE,UAAU,CAAC,CAAC;YAC5D,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,EAAE,CAAC;QACvB,CAAC;IACH,CAAC;CACF"}

package/dist/core/DesktopHelperRetention.d.ts

@@ -0,0 +1,89 @@
+export declare const HELPER_MANIFEST_SUFFIX = ".json";
+export declare const RETAINED_HELPER_NAME = "instar-desktop-host";
+export type DesktopHelperFallback = 'disabled' | 'no-manifest' | 'not-release-build' | 'older-than-retained' | 'same-version-different-source' | 'retained-unsafe' | 'retained-unrunnable' | 'copy-failed';
+export interface DesktopHelperRecord {
+    sourceHash: string;
+    binarySha256: string;
+    packageVersion: string;
+    /** The source hash this Mac last proved it holds the helper's own grant for. */
+    grantedSourceHash: string | null;
+    replacedAt: string;
+}
+export interface DesktopHelperResolution {
+    path: string;
+    source: 'retained' | 'packaged';
+    reason?: DesktopHelperFallback;
+}
+/** Why a missing permission needs a person. `same-program` means a grant was
+ * removed by someone or something else, so no update story applies. */
+export type DesktopHelperPermissionChange = {
+    kind: 'source-changed';
+    version: string;
+    helperPath: string;
+} | {
+    kind: 'first-grant';
+    version: string;
+    helperPath: string;
+};
+export interface DesktopHelperRetentionOptions {
+    packagedBinary: string;
+    packageVersion: string;
+    /** Default `~/.instar/desktop-helper`. */
+    root?: string;
+    enabled?: boolean;
+    log?: (message: string) => void;
+}
+export declare function helperManifestPath(binary: string): string;
+/** Plain numeric comparison: instar versions are dotted integers. */
+export declare function compareVersions(a: string, b: string): number;
+export declare class DesktopHelperRetention {
+    private readonly options;
+    readonly root: string;
+    readonly retainedPath: string;
+    private readonly recordPath;
+    private readonly enabled;
+    private readonly log;
+    /** Verifying means hashing, so it reruns only when the kept file changes. */
+    private verified;
+    private broken;
+    /** A failed copy waits before it is tried again, because probes run twice a second. */
+    private copyRetryAt;
+    private copyRetryMs;
+    private grantNoteFailed;
+    constructor(options: DesktopHelperRetentionOptions);
+    private packaged;
+    private packagedSourceHash;
+    /** A local development build is thin. Only a release build may take the Mac's
+     * one kept copy, so a test checkout can never replace what is granted. */
+    private isReleaseBuild;
+    private readRecord;
+    private writeRecord;
+    /** The kept copy runs with the Mac's permissions, so it must be a plain file
+     * this user owns that nobody else can write, in a folder with the same rule. */
+    private safeToRun;
+    /** The rename means a helper already running keeps its old file, and macOS
+     * never sees a signed program change underneath a live process. */
+    private install;
+    /** Which helper to launch. Synchronous and cheap on the repeat path. Never
+     * throws: a probe that rejects reads as a lost grant and revokes a session. */
+    resolve(): DesktopHelperResolution;
+    private resolveKept;
+    private matchesRecord;
+    private resolveFully;
+    /** The kept copy would not run at all, so stop using it until a restart. */
+    markBroken(): void;
+    /** The kept copy holds its own grant for its current source. Failing to write
+     * that down costs nothing but a repeat at the next probe, so it never throws. */
+    noteGranted(): void;
+    /** Null when the missing permission has nothing to do with an update. */
+    permissionChange(): DesktopHelperPermissionChange | null;
+    /** The source hash this notice is about. Stable across agents on this Mac. */
+    currentSourceHash(): string | null;
+    private noticePath;
+    /** True for the first caller on this Mac for this helper. One Mac, one item.
+     * Creating the marker is atomic, so agents restarting together cannot both win. */
+    claimNotice(): boolean;
+    /** Hands the notice back when raising it failed, or once it is resolved. */
+    releaseNotice(): void;
+}
+//# sourceMappingURL=DesktopHelperRetention.d.ts.map

package/dist/core/DesktopHelperRetention.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DesktopHelperRetention.d.ts","sourceRoot":"","sources":["../../src/core/DesktopHelperRetention.ts"],"names":[],"mappings":"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"}

package/dist/core/DesktopHelperRetention.js

@@ -0,0 +1,299 @@
+/**
+ * DesktopHelperRetention: one kept copy of the Mac desktop helper per Mac, at
+ * one path that updates never touch.
+ *
+ * macOS ties a Screen Recording or Accessibility grant to the exact program.
+ * For an ad-hoc signed helper that means its hash, and for a helper with no app
+ * bundle it means its path too. So the installed copy is a poor place to hold a
+ * grant: each agent on a Mac has its own, and an update can replace its bytes.
+ * The kept copy changes only when the helper's SOURCE changes (the build writes
+ * a source hash beside the binary), so a rebuild of unchanged source on a newer
+ * toolchain cannot cost a grant, and every agent on a Mac shares one macOS
+ * entry. A Developer ID identity later keeps that same entry across source
+ * changes too, because the path never moves.
+ *
+ * When the source really does change, the old grant cannot follow it. This
+ * module records that fact so the machine can say so plainly.
+ *
+ * Every failure falls back to the installed copy with a named reason: this
+ * module may never make a Mac less reachable than it already was.
+ */
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { SafeFsExecutor } from './SafeFsExecutor.js';
+export const HELPER_MANIFEST_SUFFIX = '.json';
+export const RETAINED_HELPER_NAME = 'instar-desktop-host';
+const RECORD_NAME = 'retained.json';
+const FAT_MAGIC = 0xcafebabe;
+const COPY_RETRY_FIRST_MS = 60_000;
+const COPY_RETRY_MAX_MS = 60 * 60_000;
+export function helperManifestPath(binary) {
+    return `${binary}${HELPER_MANIFEST_SUFFIX}`;
+}
+/** Plain numeric comparison: instar versions are dotted integers. */
+export function compareVersions(a, b) {
+    const parts = (value) => value.split('.').map(part => Number.parseInt(part, 10) || 0);
+    const left = parts(a);
+    const right = parts(b);
+    for (let i = 0; i < Math.max(left.length, right.length); i++) {
+        const difference = (left[i] ?? 0) - (right[i] ?? 0);
+        if (difference !== 0)
+            return Math.sign(difference);
+    }
+    return 0;
+}
+function sha256(file) {
+    return crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex');
+}
+export class DesktopHelperRetention {
+    options;
+    root;
+    retainedPath;
+    recordPath;
+    enabled;
+    log;
+    /** Verifying means hashing, so it reruns only when the kept file changes. */
+    verified = null;
+    broken = false;
+    /** A failed copy waits before it is tried again, because probes run twice a second. */
+    copyRetryAt = 0;
+    copyRetryMs = COPY_RETRY_FIRST_MS;
+    grantNoteFailed = false;
+    constructor(options) {
+        this.options = options;
+        this.root = options.root ?? path.join(os.homedir(), '.instar', 'desktop-helper');
+        this.retainedPath = path.join(this.root, RETAINED_HELPER_NAME);
+        this.recordPath = path.join(this.root, RECORD_NAME);
+        this.enabled = options.enabled !== false;
+        this.log = options.log ?? (message => console.warn(message));
+    }
+    packaged(reason) {
+        return { path: this.options.packagedBinary, source: 'packaged', reason };
+    }
+    packagedSourceHash() {
+        try {
+            const parsed = JSON.parse(fs.readFileSync(helperManifestPath(this.options.packagedBinary), 'utf8'));
+            return typeof parsed.sourceHash === 'string' && /^[a-f0-9]{64}$/.test(parsed.sourceHash) ? parsed.sourceHash : null;
+        }
+        catch {
+            return null; // @silent-fallback-ok — resolve() reports this as the named reason no-manifest.
+        }
+    }
+    /** A local development build is thin. Only a release build may take the Mac's
+     * one kept copy, so a test checkout can never replace what is granted. */
+    isReleaseBuild() {
+        let handle = null;
+        try {
+            handle = fs.openSync(this.options.packagedBinary, 'r');
+            const head = Buffer.alloc(4);
+            return fs.readSync(handle, head, 0, 4, 0) === 4 && head.readUInt32BE(0) === FAT_MAGIC;
+        }
+        catch {
+            return false; // @silent-fallback-ok — resolve() reports this as not-release-build.
+        }
+        finally {
+            if (handle !== null)
+                fs.closeSync(handle);
+        }
+    }
+    readRecord() {
+        try {
+            const value = JSON.parse(fs.readFileSync(this.recordPath, 'utf8'));
+            if (typeof value.sourceHash !== 'string' || typeof value.binarySha256 !== 'string'
+                || typeof value.packageVersion !== 'string')
+                return null;
+            return {
+                sourceHash: value.sourceHash, binarySha256: value.binarySha256, packageVersion: value.packageVersion,
+                grantedSourceHash: typeof value.grantedSourceHash === 'string' ? value.grantedSourceHash : null,
+                replacedAt: typeof value.replacedAt === 'string' ? value.replacedAt : '',
+            };
+        }
+        catch {
+            return null; // @silent-fallback-ok — no readable record means the copy is reinstalled from the package.
+        }
+    }
+    writeRecord(record) {
+        const temporary = `${this.recordPath}.${process.pid}.tmp`;
+        fs.writeFileSync(temporary, `${JSON.stringify(record, null, 2)}\n`, { mode: 0o600 });
+        fs.renameSync(temporary, this.recordPath);
+    }
+    /** The kept copy runs with the Mac's permissions, so it must be a plain file
+     * this user owns that nobody else can write, in a folder with the same rule. */
+    safeToRun() {
+        try {
+            const uid = process.getuid?.();
+            for (const candidate of [this.root, this.retainedPath]) {
+                const stat = fs.lstatSync(candidate);
+                if (stat.isSymbolicLink() || stat.uid !== uid || (stat.mode & 0o022) !== 0)
+                    return false;
+            }
+            return fs.lstatSync(this.retainedPath).isFile();
+        }
+        catch {
+            return false; // @silent-fallback-ok — an unreadable copy is unsafe; resolve() names retained-unsafe.
+        }
+    }
+    /** The rename means a helper already running keeps its old file, and macOS
+     * never sees a signed program change underneath a live process. */
+    install(sourceHash, grantedSourceHash) {
+        fs.mkdirSync(this.root, { recursive: true, mode: 0o700 });
+        const temporary = `${this.retainedPath}.${process.pid}.tmp`;
+        fs.copyFileSync(this.options.packagedBinary, temporary);
+        fs.chmodSync(temporary, 0o700);
+        fs.renameSync(temporary, this.retainedPath);
+        this.writeRecord({
+            sourceHash, binarySha256: sha256(this.retainedPath), packageVersion: this.options.packageVersion,
+            grantedSourceHash,
+            replacedAt: new Date().toISOString(),
+        });
+    }
+    /** Which helper to launch. Synchronous and cheap on the repeat path. Never
+     * throws: a probe that rejects reads as a lost grant and revokes a session. */
+    resolve() {
+        if (!this.enabled)
+            return this.packaged('disabled');
+        if (this.broken)
+            return this.packaged('retained-unrunnable');
+        if (Date.now() < this.copyRetryAt)
+            return this.packaged('copy-failed');
+        try {
+            return this.resolveKept();
+        }
+        catch (error) {
+            this.verified = null;
+            this.log(`[instar] could not check the Mac desktop helper copy: ${error instanceof Error ? error.message : String(error)}`);
+            return this.packaged('retained-unsafe'); // @silent-fallback-ok — logged above; diagnostics name the reason.
+        }
+    }
+    resolveKept() {
+        try {
+            const stat = fs.statSync(this.retainedPath);
+            if (this.verified && this.verified.size === stat.size && this.verified.mtimeMs === stat.mtimeMs
+                && this.verified.ino === stat.ino)
+                return this.verified.resolution;
+        }
+        catch { /* @silent-fallback-ok — no kept copy yet; the full path below creates it. */ }
+        const resolution = this.resolveFully();
+        if (resolution.source === 'retained') {
+            const stat = fs.statSync(this.retainedPath);
+            this.verified = { size: stat.size, mtimeMs: stat.mtimeMs, ino: stat.ino, resolution };
+        }
+        else {
+            this.verified = null;
+        }
+        return resolution;
+    }
+    matchesRecord(record) {
+        try {
+            return sha256(this.retainedPath) === record.binarySha256;
+        }
+        catch {
+            return false; // @silent-fallback-ok — unreadable bytes are damaged bytes; resolveFully restores them.
+        }
+    }
+    resolveFully() {
+        const sourceHash = this.packagedSourceHash();
+        if (!sourceHash)
+            return this.packaged('no-manifest');
+        if (!this.isReleaseBuild())
+            return this.packaged('not-release-build');
+        const record = this.readRecord();
+        const fileExists = fs.existsSync(this.retainedPath);
+        if (record && record.sourceHash !== sourceHash) {
+            const order = compareVersions(this.options.packageVersion, record.packageVersion);
+            // Agents on one Mac update minutes apart. The older one must not swap
+            // the helper back and cost the newer one its grant.
+            if (order < 0)
+                return this.packaged('older-than-retained');
+            if (order === 0)
+                return this.packaged('same-version-different-source');
+        }
+        const intact = !!record && record.sourceHash === sourceHash && fileExists
+            && this.safeToRun() && this.matchesRecord(record);
+        if (intact)
+            return { path: this.retainedPath, source: 'retained' };
+        if (record?.sourceHash === sourceHash && fileExists) {
+            this.log('[instar] retained Mac desktop helper failed its integrity check; restoring it from this package');
+        }
+        try {
+            // A real source change keeps the old proof, which is how the Mac can say
+            // the helper changed. Restoring a damaged copy writes bytes macOS has not
+            // seen, so the proof is gone and the Mac must say it needs a grant.
+            this.install(sourceHash, record && record.sourceHash !== sourceHash ? record.grantedSourceHash : null);
+            this.copyRetryAt = 0;
+            this.copyRetryMs = COPY_RETRY_FIRST_MS;
+        }
+        catch (error) {
+            this.copyRetryAt = Date.now() + this.copyRetryMs;
+            this.copyRetryMs = Math.min(this.copyRetryMs * 2, COPY_RETRY_MAX_MS);
+            this.log(`[instar] could not keep a Mac desktop helper copy: ${error instanceof Error ? error.message : String(error)}`);
+            return this.packaged('copy-failed'); // @silent-fallback-ok — logged above; diagnostics name copy-failed.
+        }
+        return this.safeToRun() ? { path: this.retainedPath, source: 'retained' } : this.packaged('retained-unsafe');
+    }
+    /** The kept copy would not run at all, so stop using it until a restart. */
+    markBroken() {
+        this.broken = true;
+        this.verified = null;
+        this.log('[instar] retained Mac desktop helper would not run; using the installed copy');
+    }
+    /** The kept copy holds its own grant for its current source. Failing to write
+     * that down costs nothing but a repeat at the next probe, so it never throws. */
+    noteGranted() {
+        const record = this.readRecord();
+        if (!record || record.grantedSourceHash === record.sourceHash)
+            return;
+        try {
+            this.writeRecord({ ...record, grantedSourceHash: record.sourceHash });
+            this.releaseNotice();
+            this.grantNoteFailed = false;
+        }
+        catch (error) { // @silent-fallback-ok — logged once below; the next probe writes the grant again.
+            if (!this.grantNoteFailed) {
+                this.log(`[instar] could not record the Mac desktop helper grant: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            this.grantNoteFailed = true;
+        }
+    }
+    /** Null when the missing permission has nothing to do with an update. */
+    permissionChange() {
+        const record = this.readRecord();
+        if (!record)
+            return null;
+        const base = { version: record.packageVersion, helperPath: this.retainedPath };
+        if (!record.grantedSourceHash)
+            return { kind: 'first-grant', ...base };
+        return record.grantedSourceHash === record.sourceHash ? null : { kind: 'source-changed', ...base };
+    }
+    /** The source hash this notice is about. Stable across agents on this Mac. */
+    currentSourceHash() {
+        return this.readRecord()?.sourceHash ?? null;
+    }
+    noticePath() {
+        const hash = this.currentSourceHash();
+        return hash ? path.join(this.root, `notice-${hash.slice(0, 16)}`) : null;
+    }
+    /** True for the first caller on this Mac for this helper. One Mac, one item.
+     * Creating the marker is atomic, so agents restarting together cannot both win. */
+    claimNotice() {
+        const marker = this.noticePath();
+        if (!marker)
+            return false;
+        try {
+            fs.writeFileSync(marker, '', { flag: 'wx', mode: 0o600 });
+            return true;
+        }
+        catch {
+            return false; // @silent-fallback-ok — the marker exists, so another agent holds this notice.
+        }
+    }
+    /** Hands the notice back when raising it failed, or once it is resolved. */
+    releaseNotice() {
+        const marker = this.noticePath();
+        if (marker)
+            SafeFsExecutor.safeRmSync(marker, { force: true, operation: 'src/core/DesktopHelperRetention.ts:releaseNotice' });
+    }
+}
+//# sourceMappingURL=DesktopHelperRetention.js.map

package/dist/core/DesktopHelperRetention.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DesktopHelperRetention.js","sourceRoot":"","sources":["../../src/core/DesktopHelperRetention.ts"],"names":[],"mappings":"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"}

package/dist/core/DesktopHost.d.ts

@@ -1,3 +1,4 @@
+import type { DesktopHelperPermissionChange } from './DesktopHelperRetention.js';
 /** Machine-local capture and input boundary. A Windows or Linux companion
  * implements this contract only after its own permission and live-session proof. */
 export type DesktopButton = 'left' | 'right' | 'middle';
@@ -56,6 +57,10 @@ export interface DesktopProbe {
      * itself; `inherited` depends on what started this server's process tree. */
     screenGrant?: 'own' | 'inherited' | 'none';
     inputGrant?: 'own' | 'inherited' | 'none';
+    /** macOS only: which copy of the helper ran, and why a person is needed. */
+    helperSource?: 'retained' | 'packaged';
+    helperFallback?: string;
+    helperChange?: DesktopHelperPermissionChange;
 }
 export type DesktopPlatform = 'macos' | 'windows';
 export interface DesktopDisplay {

package/dist/core/DesktopHost.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DesktopHost.d.ts","sourceRoot":"","sources":["../../src/core/DesktopHost.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"DesktopHost.d.ts","sourceRoot":"","sources":["../../src/core/DesktopHost.ts"],"names":[],"mappings":"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"}

package/dist/core/DesktopHost.js.map

@@ -1 +1 @@
-{"version":3,"file":"DesktopHost.js","sourceRoot":"","sources":["../../src/core/DesktopHost.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"DesktopHost.js","sourceRoot":"","sources":["../../src/core/DesktopHost.ts"],"names":[],"mappings":"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"}

package/dist/core/DesktopProbeReadiness.d.ts

@@ -1,3 +1,6 @@
+/** A probe reports the helper's view of a desktop session, not whether the
+ * machine or the Instar agent is online or whether a screen is actually locked. */
+import type { DesktopHelperPermissionChange } from './DesktopHelperRetention.js';
 /** One sentence on what is wrong, then the one thing that fixes it. */
 export declare function desktopProbeUnavailableReason(probe: {
     sessionActive: boolean;
@@ -8,5 +11,6 @@ export declare function desktopProbeUnavailableReason(probe: {
     onConsole?: boolean;
     loginDone?: boolean;
     screenLocked?: boolean;
+    helperChange?: DesktopHelperPermissionChange;
 }): string;
 //# sourceMappingURL=DesktopProbeReadiness.d.ts.map

package/dist/core/DesktopProbeReadiness.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DesktopProbeReadiness.d.ts","sourceRoot":"","sources":["../../src/core/DesktopProbeReadiness.ts"],"names":[],"mappings":"AAIA,uEAAuE;AACvE,wBAAgB,6BAA6B,CAAC,KAAK,EAAE;IACnD,aAAa,EAAE,OAAO,CAAC;IACvB,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,eAAe,EAAE,OAAO,CAAC;IACzB,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB,GAAG,MAAM,CA8BT"}
+{"version":3,"file":"DesktopProbeReadiness.d.ts","sourceRoot":"","sources":["../../src/core/DesktopProbeReadiness.ts"],"names":[],"mappings":"AAAA;mFACmF;AACnF,OAAO,KAAK,EAAE,6BAA6B,EAAE,MAAM,6BAA6B,CAAC;AAcjF,uEAAuE;AACvE,wBAAgB,6BAA6B,CAAC,KAAK,EAAE;IACnD,aAAa,EAAE,OAAO,CAAC;IACvB,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,eAAe,EAAE,OAAO,CAAC;IACzB,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,YAAY,CAAC,EAAE,6BAA6B,CAAC;CAC9C,GAAG,MAAM,CAiCT"}

package/dist/core/DesktopProbeReadiness.js

@@ -1,13 +1,22 @@
-/** A probe reports the helper's view of a desktop session, not whether the
- * machine or the Instar agent is online or whether a screen is actually locked. */
 const PERMISSION_STEP = 'System Settings → Privacy & Security';
+/** macOS ties these permissions to the exact program, so a changed helper loses
+ * them and nothing on the Mac can restore them without a person. Say that. */
+function helperChangeReason(change, missing) {
+    const why = change.kind === 'source-changed'
+        ? `Instar's Mac desktop helper changed in update ${change.version}, and macOS ties ${missing} to the exact program, so the old permission no longer applies.`
+        : `Instar now keeps one permanent copy of its Mac desktop helper, so later updates that leave the helper unchanged cannot remove its permission. macOS needs to allow that copy once.`;
+    return `${why} This will not fix itself. Someone at this Mac needs to allow it again: ${PERMISSION_STEP} → ${missing}. `
+        + `Turn instar-desktop-host off and on. If it is not listed or that does not work, remove it with the minus button and add ${change.helperPath} with the plus button. Then tap Retry.`;
+}
 /** One sentence on what is wrong, then the one thing that fixes it. */
 export function desktopProbeUnavailableReason(probe) {
     const missing = [!probe.screenPermission && 'Screen Recording',
         !probe.inputPermission && 'Accessibility'].filter(Boolean).join(' and ');
-    const permissionStep = missing
-        ? `It also needs a one-time ${missing} permission at the Mac: ${PERMISSION_STEP} → ${missing} → turn on instar-desktop-host.`
-        : '';
+    const permissionStep = missing && probe.helperChange
+        ? helperChangeReason(probe.helperChange, missing)
+        : missing
+            ? `It also needs a one-time ${missing} permission at the Mac: ${PERMISSION_STEP} → ${missing} → turn on instar-desktop-host.`
+            : '';
     if (!probe.sessionActive) {
         if (probe.consoleSessionPresent === false) {
             return 'Nobody is signed in at this Mac’s screen, so the desktop helper cannot see a console session. Sign in at the Mac. The Instar agent is online.';
@@ -26,6 +35,8 @@ export function desktopProbeUnavailableReason(probe) {
     }
     if (probe.displayCount === 0)
         return 'No active display is available to capture on this machine. Wake its screen or connect a display.';
+    if (missing && probe.helperChange)
+        return helperChangeReason(probe.helperChange, missing);
     if (!probe.screenPermission) {
         return `Screen capture permission is unavailable to the desktop helper. Turn it on once at the Mac: ${PERMISSION_STEP} → Screen Recording → instar-desktop-host, then tap Retry.`;
     }