From de9d34e7cbf57f9dfaf6442c3fa23fa60758745f Mon Sep 17 00:00:00 2001
From: Maurice Schmicking <17197791+mschmicking@users.noreply.github.com>
Date: Mon, 17 Aug 2026 23:14:45 +0200
Subject: [PATCH] feat(cli): sweep the adapter markers a deleted script leaves
 behind
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The javascript adapter keeps two bookkeeping states beside every script, on every
javascript instance rather than only the one that runs it:

    javascript.<n>.scriptEnabled.<id>
    javascript.<n>.scriptProblem.<id>

Both are created by the adapter's load(), which calls createActiveObject and
createProblemObject before prepareScript checks common.engine to decide whether
this instance should run the script at all. Every instance runs load() for every
non-global script at startup and again on every source change, so all of them hold
a pair for every script.

Deletion, though, is gated on the engine: only the instance that owned the script
at the moment it was deleted removes its own pair. Every other instance keeps one
for a script that no longer exists, js-controller warns about it for the life of
the system, and nothing in ioBroker ever collects it. This is independent of who
deleted the script — the Admin UI leaves the identical residue.

remove, rename and move now sweep both markers of the id they just deleted. The
sweep runs after the object is gone and after the trash backup, and is best-effort:
it warns rather than turning a completed delete into a failure. Order is enforced
in ObjectsApi.deleteScriptMarker — value first, object second, never the reverse,
because an object deleted out from under a surviving value is exactly the orphan
being cleaned up. (The adapter's own cleanup gets this backwards, which is a likely
source of the "state has no object" warnings.)

remove also stops refusing an id whose script is already gone when markers remain,
since otherwise pre-existing ones cannot be cleared by anything. It sweeps them,
touches nothing else, and keeps the local file.

doctor gains a read-only `markers` check that counts both kinds, names the orphans,
and warns rather than fails — nothing here is broken.

Both kinds are handled through MARKER_KINDS in types.ts rather than a pattern
repeated per call site: an earlier draft covered only scriptEnabled and left eight
orphaned scriptProblem states on a live instance while doctor reported it clean.

Verified against ioBroker.javascript v8.9.2 on a live three-instance system, and
covered by tests against the in-process fake server.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 AGENTS.md                         |  16 +++
 README.md                         |  40 +++---
 docs/TROUBLESHOOTING.md           |  48 ++++++-
 src/client/objects.ts             | 125 +++++++++++++++++
 src/commands/doctor.ts            |  85 ++++++++++-
 src/commands/remove.ts            | 105 +++++++++++++-
 src/commands/rename.ts            |   7 +-
 src/types.ts                      |  53 +++++++
 test/commands-destructive.test.ts | 177 +++++++++++++++++++++++
 test/commands-doctor.test.ts      |  83 ++++++++++-
 test/fake-server.ts               |  87 ++++++++++++
 test/objects.test.ts              | 226 ++++++++++++++++++++++++++++++
 12 files changed, 1014 insertions(+), 38 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index bbf6ce8..b8c910d 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -31,6 +31,22 @@ instruction from the user:
 4. **Deletion is explicit.** Only `remove`, `rename` and `move` delete anything, each
    requires `--yes`, and each writes the full object JSON to `.iobroker-sync/trash/`
    _before_ deleting. A failed backup aborts the operation.
+
+   The one thing they delete without backing it up is the pair of adapter markers
+   belonging to the script being deleted — `javascript.<n>.scriptEnabled.<id>` and
+   `javascript.<n>.scriptProblem.<id>` — and only after that script is gone. Those are
+   adapter-generated derived state (`common.enabled` and `common.engine` are already in
+   the trash copy), so there is nothing in them to lose. See `cleanUpScriptMarkers` in
+   `commands/remove.ts` for why they have to be swept at all, and
+   `ObjectsApi.deleteScriptMarker` for the ordering rule (value first, object second,
+   never the reverse). The sweep is best-effort: it warns, it never fails the command.
+
+   **Both kinds or neither.** The adapter creates and deletes the two together, so code
+   that handles only `scriptEnabled` cleans up half a mess and reports success. That is
+   not hypothetical: the first version of this sweep shipped that way and left eight
+   orphaned `scriptProblem` states on a live instance while `doctor` called it clean.
+   `MARKER_KINDS` in `types.ts` is the single list; anything iterating markers iterates it.
+
 5. **Copy-then-delete must verify first.** ioBroker has no native rename/move, so both
    are implemented as copy-verify-delete. The verification compares the actual source
    text. Checking only that "something exists at the new id" is not verification — a
diff --git a/README.md b/README.md
index 80f1cd7..718d2b2 100644
--- a/README.md
+++ b/README.md
@@ -108,29 +108,29 @@ If `logs` shows nothing, that is usually the adapter's own log level rather than
 
 **Sync**
 
-| Command            | Description                                                                                                                                                             |
-| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `init`             | Write `.iobroker-sync.json`, verify the connection, create the script folder. Asks interactively when run without flags. `--types` also sets up TypeScript definitions. |
-| `types`            | Set up editor intellisense (`log`, `schedule`, ...). `--force`, `--offline`.                                                                                            |
-| `login` / `logout` | Save or remove the password for this instance. Never stored in the project.                                                                                             |
-| `trust`            | Accept the instance's current TLS certificate. Only needed after it changes. `--yes` skips the prompt.                                                                  |
-| `doctor`           | Check config, certificate, login, connection and a live round-trip, and say which one is wrong. Read-only, never prompts. Run this first when something looks broken.   |
-| `pull [pattern]`   | Download scripts to disk. Never deletes or overwrites local files.                                                                                                      |
-| `push [pattern]`   | Upload locally modified scripts. Never deletes remote objects.                                                                                                          |
-| `status`           | Show what changed, locally and remotely.                                                                                                                                |
-| `diff [pattern]`   | Unified diff of local vs server. `--against <snapshot>` compares with a backup instead.                                                                                 |
-| `watch`            | Push on save. `--pull` also applies remote changes.                                                                                                                     |
-| `logs [pattern]`   | Stream the server log. `--level`, `--limit`. Read-only.                                                                                                                 |
-| `backup [pattern]` | Snapshot every script — source _and_ full object — to `.iobroker-sync/backup/<timestamp>/`. Read-only against the server.                                               |
+| Command            | Description                                                                                                                                                                                     |
+| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `init`             | Write `.iobroker-sync.json`, verify the connection, create the script folder. Asks interactively when run without flags. `--types` also sets up TypeScript definitions.                         |
+| `types`            | Set up editor intellisense (`log`, `schedule`, ...). `--force`, `--offline`.                                                                                                                    |
+| `login` / `logout` | Save or remove the password for this instance. Never stored in the project.                                                                                                                     |
+| `trust`            | Accept the instance's current TLS certificate. Only needed after it changes. `--yes` skips the prompt.                                                                                          |
+| `doctor`           | Check config, certificate, login, connection, a live round-trip and leftover adapter markers, and say which one is wrong. Read-only, never prompts. Run this first when something looks broken. |
+| `pull [pattern]`   | Download scripts to disk. Never deletes or overwrites local files.                                                                                                                              |
+| `push [pattern]`   | Upload locally modified scripts. Never deletes remote objects.                                                                                                                                  |
+| `status`           | Show what changed, locally and remotely.                                                                                                                                                        |
+| `diff [pattern]`   | Unified diff of local vs server. `--against <snapshot>` compares with a backup instead.                                                                                                         |
+| `watch`            | Push on save. `--pull` also applies remote changes.                                                                                                                                             |
+| `logs [pattern]`   | Stream the server log. `--level`, `--limit`. Read-only.                                                                                                                                         |
+| `backup [pattern]` | Snapshot every script — source _and_ full object — to `.iobroker-sync/backup/<timestamp>/`. Read-only against the server.                                                                       |
 
 **Lifecycle**
 
-| Command                                  | Description                                                                                                       |
-| ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
-| `list`                                   | All scripts with instance and enabled state.                                                                      |
-| `start` / `stop` / `restart` `<pattern>` | Toggle `common.enabled`.                                                                                          |
-| `new <path>`                             | Create a new script (disabled) plus any missing folders.                                                          |
-| `rename` / `move` / `remove`             | Destructive. Require `--yes` and back up the object first. `remove` keeps the local file unless `--delete-local`. |
+| Command                                  | Description                                                                                                                                                                                                                                 |
+| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `list`                                   | All scripts with instance and enabled state.                                                                                                                                                                                                |
+| `start` / `stop` / `restart` `<pattern>` | Toggle `common.enabled`.                                                                                                                                                                                                                    |
+| `new <path>`                             | Create a new script (disabled) plus any missing folders.                                                                                                                                                                                    |
+| `rename` / `move` / `remove`             | Destructive. Require `--yes` and back up the object first. `remove` keeps the local file unless `--delete-local`. All three also clean up the `scriptEnabled`/`scriptProblem` states the old id leaves behind on every javascript instance. |
 
 `--dry-run`, `--verbose`, `--json` and `-C <dir>` are global and work with every command.
 When in doubt, `--dry-run` shows what would happen and changes nothing.
diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md
index 818e9f1..4288e85 100644
--- a/docs/TROUBLESHOOTING.md
+++ b/docs/TROUBLESHOOTING.md
@@ -3,9 +3,9 @@
 Things that look like bugs and are not. See the [README](../README.md) for the overview.
 
 **Start with `iob-sync doctor`.** It checks the config, the certificate, the login, the
-connection and a live round-trip, and names the one that is wrong — including the two
-cases below, which are the ones that reliably send people down the wrong path. It is
-read-only and never prompts, so it is safe to run at any time.
+connection, a live round-trip and the adapter's leftover script markers, and names the one
+that is wrong — including the cases below, which are the ones that reliably send people
+down the wrong path. It is read-only and never prompts, so it is safe to run at any time.
 
 ## Commands time out, but the connection "works"
 
@@ -86,6 +86,48 @@ a script or move it to another javascript instance, it cannot — that is delibe
 sync bug cannot stop a running script. Use `start` / `stop` for `enabled`; instance moves
 must be done in Admin.
 
+## `doctor` warns about orphaned markers
+
+Nothing is broken, and no script is affected.
+
+The javascript adapter keeps two bookkeeping states beside every script, on **every**
+javascript instance — not only the one that runs it:
+
+```
+javascript.<n>.scriptEnabled.<script id>
+javascript.<n>.scriptProblem.<script id>
+```
+
+Both are created by the adapter's `load()`, which calls `createActiveObject` and
+`createProblemObject` _before_ `prepareScript` checks `common.engine` to decide whether
+this instance should actually run the script. Every instance runs `load()` for every
+non-global script at startup, and again on every source change. So on a three-instance
+system, ten scripts mean sixty of these states, and that is normal.
+
+Deletion, however, _is_ gated on the engine: only the instance that owned the script at
+the moment it was deleted removes its own pair. The pairs on the other instances stay for
+the life of the system, js-controller complains about them, and nothing in ioBroker ever
+collects them.
+
+This has nothing to do with who did the deleting — the Admin UI leaves exactly the same
+residue. Verified against ioBroker.javascript v8.9.2.
+
+`iob-sync doctor` lists them by id, both kinds. To clear one script's leftovers:
+
+```bash
+iob-sync remove script.js.diag.retired-check --yes
+```
+
+`remove` sweeps the markers even when the script itself is already gone from the server —
+in that case it deletes nothing else and leaves your local file alone. `rename` and `move`
+sweep the old id's markers as they go, so this does not accumulate from normal use.
+
+One detail worth knowing if you clean these up by hand: delete the **state value first,
+then the object**. The reverse order leaves a value with no object behind it, which is the
+shape js-controller actually warns about — and it is the order the adapter's own cleanup
+uses (`delObject` then `delState`), so that warning may well have come from ioBroker
+itself rather than from anything you did.
+
 ## A push is refused as a conflict
 
 Local and remote both changed since the last sync. Inspect with `iob-sync diff`, then
diff --git a/src/client/objects.ts b/src/client/objects.ts
index 380e446..72d5ac4 100644
--- a/src/client/objects.ts
+++ b/src/client/objects.ts
@@ -6,9 +6,12 @@
 import {
   FolderObject,
   IoBrokerObject,
+  MARKER_KINDS,
+  MarkerKind,
   ObjectsApi,
   ObjectViewResult,
   ScriptCommon,
+  ScriptMarkerEntry,
   ScriptObject,
   SocketClient,
 } from '../types';
@@ -17,6 +20,43 @@ const SCRIPT_NAMESPACE = 'script.js.';
 // Verified endkey used by the Admin UI itself to bound a getObjectView range scan.
 const VIEW_ENDKEY = `${SCRIPT_NAMESPACE}香`;
 
+const JS_NAMESPACE = 'javascript.';
+
+/** `javascript.*.<kind>.*` — every instance's markers of one kind, for every script. */
+function markerPattern(kind: MarkerKind): string {
+  return `${JS_NAMESPACE}*.${kind}.*`;
+}
+
+/**
+ * Splits a marker id into the script it belongs to and which kind it is:
+ * `javascript.2.scriptEnabled.common.garage` -> `script.js.common.garage`, scriptEnabled.
+ *
+ * Returns null for anything that is not one — including ids with something other than
+ * a bare instance number in front of the kind, so that a state someone else parked
+ * under `javascript.` cannot be mistaken for ours and deleted.
+ */
+export function parseMarkerId(stateId: string): { scriptId: string; kind: MarkerKind } | null {
+  if (!stateId.startsWith(JS_NAMESPACE)) {
+    return null;
+  }
+  for (const kind of MARKER_KINDS) {
+    const infix = `.${kind}.`;
+    const kindAt = stateId.indexOf(infix);
+    if (kindAt === -1) {
+      continue;
+    }
+    const instance = stateId.slice(JS_NAMESPACE.length, kindAt);
+    if (!/^\d+$/.test(instance)) {
+      continue;
+    }
+    const suffix = stateId.slice(kindAt + infix.length);
+    if (suffix) {
+      return { scriptId: `${SCRIPT_NAMESPACE}${suffix}`, kind };
+    }
+  }
+  return null;
+}
+
 export class AdminObjectsApi implements ObjectsApi {
   constructor(private readonly socket: SocketClient) {}
 
@@ -111,4 +151,89 @@ export class AdminObjectsApi implements ObjectsApi {
   async deleteObject(id: string): Promise<void> {
     await this.socket.emit('delObject', [id]);
   }
+
+  /**
+   * Reads the value side and the object side separately and unions them, because a
+   * marker can exist as either half alone and the halves are what we need to tell apart.
+   *
+   * One half failing is tolerated: `getStates` and `getForeignObjects` are separate
+   * commands with separate histories across Admin versions, and a partial answer here
+   * still beats reporting nothing. Only a total failure propagates.
+   */
+  async listScriptMarkers(): Promise<ScriptMarkerEntry[]> {
+    const perKind = await Promise.all(MARKER_KINDS.map((kind) => this.listMarkersOfKind(kind)));
+    return perKind.flat().sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+  }
+
+  private async listMarkersOfKind(kind: MarkerKind): Promise<ScriptMarkerEntry[]> {
+    const pattern = markerPattern(kind);
+    const [values, objects] = await Promise.allSettled([
+      this.readMarkerValues(pattern),
+      this.socket.emit<Record<string, unknown> | null>('getForeignObjects', [pattern, 'state']),
+    ]);
+
+    if (values.status === 'rejected' && objects.status === 'rejected') {
+      throw values.reason;
+    }
+
+    const valueIds = new Set(values.status === 'fulfilled' ? Object.keys(values.value ?? {}) : []);
+    const objectIds = new Set(
+      objects.status === 'fulfilled' ? Object.keys(objects.value ?? {}) : [],
+    );
+
+    const entries: ScriptMarkerEntry[] = [];
+    for (const id of new Set([...valueIds, ...objectIds])) {
+      const parsed = parseMarkerId(id);
+      // The pattern is a wildcard match, so it can catch ids that merely look the part
+      // (`javascript.0.scriptEnabled` with no suffix, or a non-numeric instance).
+      // parseMarkerId is the authority on what is really ours.
+      if (parsed?.kind !== kind) {
+        continue;
+      }
+      entries.push({
+        id,
+        scriptId: parsed.scriptId,
+        kind,
+        hasValue: valueIds.has(id),
+        hasObject: objectIds.has(id),
+      });
+    }
+    return entries;
+  }
+
+  /**
+   * `getStates` is the current command; `getForeignStates` is its deprecated alias and
+   * the only one older Admin builds answer. Trying both costs one extra round trip on
+   * instances that need it and nothing on instances that do not.
+   */
+  private async readMarkerValues(pattern: string): Promise<Record<string, unknown> | null> {
+    try {
+      return await this.socket.emit<Record<string, unknown> | null>('getStates', [pattern]);
+    } catch {
+      return this.socket.emit<Record<string, unknown> | null>('getForeignStates', [pattern]);
+    }
+  }
+
+  async deleteScriptMarker(entry: ScriptMarkerEntry): Promise<void> {
+    if (!parseMarkerId(entry.id)) {
+      // Belt and braces: this API is reachable from command code, and the whole point
+      // of it is deleting things, so it refuses anything outside its own namespace.
+      throw new Error(`Refusing to delete "${entry.id}": not a script marker.`);
+    }
+
+    // Value first. If this throws we stop here on purpose — deleting the object while
+    // the value survives would manufacture the exact orphan this code exists to remove.
+    if (entry.hasValue) {
+      await this.socket.emit('delState', [entry.id]);
+    }
+
+    if (entry.hasObject) {
+      // Admin's delState is documented to take the object with it. Verify rather than
+      // assume: on an instance where it does not, the object has to go separately.
+      const remaining = await this.socket.emit<IoBrokerObject | null>('getObject', [entry.id]);
+      if (remaining) {
+        await this.socket.emit('delObject', [entry.id]);
+      }
+    }
+  }
 }
diff --git a/src/commands/doctor.ts b/src/commands/doctor.ts
index 8b6b39e..9800658 100644
--- a/src/commands/doctor.ts
+++ b/src/commands/doctor.ts
@@ -27,7 +27,7 @@ import { getAuthCookie } from '../client/auth';
 import { CertificateInfo, pinningApplies, probeCertificateInfo } from '../client/tls';
 import { loadManifest } from '../sync/manifest';
 import { scanLocal, scanRemote } from '../sync/scan';
-import { Config, Logger, UserError } from '../types';
+import { Config, Logger, ObjectsApi, UserError } from '../types';
 import * as path from 'node:path';
 
 export interface DoctorOptions {
@@ -222,6 +222,63 @@ function skipped(name: string, why: string): Check {
   return { name, status: 'skip', detail: why };
 }
 
+/**
+ * `markers` — `scriptEnabled` / `scriptProblem` states left behind by scripts that no
+ * longer exist.
+ *
+ * Worth a check of its own because nothing else on the system will ever tell you. Every
+ * javascript instance creates both markers for every non-global script — `load()` makes
+ * them before `prepareScript` checks who owns the script — but only the owning instance
+ * deletes them again. So each delete strands a pair on every other instance, and they do
+ * nothing afterwards except make js-controller warn, forever, which is precisely the kind
+ * of noise that trains people to ignore their logs.
+ *
+ * Counts both kinds. Reporting only `scriptEnabled` would have called a live instance
+ * with eight orphaned `scriptProblem` states clean — it did, before this was fixed.
+ *
+ * A warning rather than a failure: nothing is broken, and this is a read-only command.
+ */
+async function checkScriptMarkers(objects: ObjectsApi, remoteIds: Set<string>): Promise<Check> {
+  let entries;
+  try {
+    entries = await objects.listScriptMarkers();
+  } catch (err) {
+    return {
+      name: 'markers',
+      status: 'warn',
+      detail: `could not be read: ${err instanceof Error ? err.message : String(err)}`,
+    };
+  }
+
+  const orphans = entries.filter((entry) => !remoteIds.has(entry.scriptId));
+  const detail = `${entries.length} scriptEnabled/scriptProblem state(s) across all javascript instances, ${orphans.length} orphaned`;
+
+  if (orphans.length === 0) {
+    return { name: 'markers', status: 'ok', detail };
+  }
+
+  const halved = orphans.filter((entry) => entry.hasValue && !entry.hasObject).length;
+  const scripts = Array.from(new Set(orphans.map((entry) => entry.scriptId))).sort();
+
+  // The note, not the hint: report() only prints hints for failed checks, and this is
+  // the one line someone reading a warning actually needs.
+  return {
+    name: 'markers',
+    status: 'warn',
+    detail,
+    note:
+      `${orphans.length} state(s) belong to scripts that no longer exist:\n` +
+      orphans.map((entry) => `      ${entry.id}`).join('\n') +
+      (halved > 0
+        ? `\n    ${halved} of them ${halved === 1 ? 'is a value' : 'are values'} with no object ` +
+          'behind them — that is what js-controller warns about.'
+        : '') +
+      '\n    Nothing is broken, and ioBroker never collects these itself. To clear them: ' +
+      `${scripts.map((id) => `iob-sync remove ${id} --yes`).join(', ')} — ` +
+      'remove sweeps the markers even when the script itself is already gone.',
+  };
+}
+
 function statusLabel(status: CheckStatus): string {
   return status.toUpperCase().padEnd(4);
 }
@@ -241,7 +298,7 @@ export async function doctor(
   if (tls.status === 'fail') {
     const why = 'not attempted — the certificate check failed';
     checks.push(skipped('auth', why), skipped('socket', why), skipped('round-trip', why));
-    checks.push(skipped('scripts', why));
+    checks.push(skipped('scripts', why), skipped('markers', why));
     return report(checks, log);
   }
 
@@ -250,7 +307,12 @@ export async function doctor(
 
   if (auth.check.status === 'fail') {
     const why = 'not attempted — authentication failed';
-    checks.push(skipped('socket', why), skipped('round-trip', why), skipped('scripts', why));
+    checks.push(
+      skipped('socket', why),
+      skipped('round-trip', why),
+      skipped('scripts', why),
+      skipped('markers', why),
+    );
     return report(checks, log);
   }
 
@@ -279,7 +341,7 @@ export async function doctor(
         hint: err instanceof UserError ? err.hint : undefined,
       });
       const why = 'not attempted — the socket never became ready';
-      checks.push(skipped('round-trip', why), skipped('scripts', why));
+      checks.push(skipped('round-trip', why), skipped('scripts', why), skipped('markers', why));
       return report(checks, log);
     }
 
@@ -304,16 +366,21 @@ export async function doctor(
           ? 'Run `iob-sync login` to refresh the stored password, then try again.'
           : undefined,
       });
-      checks.push(skipped('scripts', 'not attempted — the instance did not answer'));
+      const why = 'not attempted — the instance did not answer';
+      checks.push(skipped('scripts', why), skipped('markers', why));
       return report(checks, log);
     }
 
+    const objects = new AdminObjectsApi(socket);
+    let remoteIds: Set<string> | undefined;
+
     try {
       const [remote, local, manifest] = await Promise.all([
-        scanRemote(new AdminObjectsApi(socket)),
+        scanRemote(objects),
         scanLocal(path.resolve(root, config.scriptRoot)),
         loadManifest(root, (msg) => log.warn(msg)),
       ]);
+      remoteIds = new Set(remote.info.keys());
       const tracked = Object.keys(manifest.entries).length;
       checks.push({
         name: 'scripts',
@@ -330,6 +397,12 @@ export async function doctor(
         hint: err instanceof UserError ? err.hint : undefined,
       });
     }
+
+    checks.push(
+      remoteIds
+        ? await checkScriptMarkers(objects, remoteIds)
+        : skipped('markers', 'not attempted — the script list could not be read'),
+    );
   } finally {
     await socket.close().catch(() => undefined);
   }
diff --git a/src/commands/remove.ts b/src/commands/remove.ts
index a1bab6c..dbad325 100644
--- a/src/commands/remove.ts
+++ b/src/commands/remove.ts
@@ -1,8 +1,75 @@
 import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
-import { CommandContext, ScriptObject, STATE_DIR, TRASH_DIRNAME, UserError } from '../types';
+import {
+  CommandContext,
+  ScriptMarkerEntry,
+  ScriptObject,
+  STATE_DIR,
+  TRASH_DIRNAME,
+  UserError,
+} from '../types';
 import { loadManifest, saveManifest, removeEntry } from '../sync/manifest';
 
+function reason(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}
+
+/**
+ * Markers left behind for `scriptId`, or an empty list if they cannot be read.
+ *
+ * Never throws. Every caller is either previewing (where a failed lookup must not
+ * turn into a failed command) or has already deleted the script (where it is far
+ * too late for this to be the thing that fails).
+ */
+export async function findScriptMarkers(
+  ctx: CommandContext,
+  scriptId: string,
+): Promise<ScriptMarkerEntry[]> {
+  try {
+    const all = await ctx.objects.listScriptMarkers();
+    return all.filter((entry) => entry.scriptId === scriptId);
+  } catch (err) {
+    ctx.log.debug(`Could not read script markers: ${reason(err)}`);
+    return [];
+  }
+}
+
+/**
+ * Removes the `javascript.<n>.scriptEnabled.<suffix>` and `.scriptProblem.<suffix>`
+ * markers a deleted script leaves behind.
+ *
+ * Every javascript instance creates both markers for every non-global script, not just
+ * the ones it runs: `load()` calls `createActiveObject`/`createProblemObject` before
+ * `prepareScript` checks `common.engine`, and every instance runs `load()` for every
+ * script at startup and again on every source change. Deletion, however, *is* gated on
+ * the engine — so a delete cleans up one instance's pair and strands one pair on each of
+ * the others. Nothing in ioBroker ever collects them, which is why we do it here.
+ *
+ * Both kinds or neither: a sweep that took only `scriptEnabled` would leave the
+ * `scriptProblem` twin behind and report success, which is exactly the bug a live
+ * instance caught after the first version of this function shipped.
+ *
+ * Best-effort on purpose. The script itself is already gone by the time this runs, so a
+ * failure here is untidiness, not data loss, and reporting it as a failed delete would be
+ * a lie. It warns and carries on.
+ */
+export async function cleanUpScriptMarkers(
+  ctx: CommandContext,
+  scriptId: string,
+  entries?: ScriptMarkerEntry[],
+): Promise<void> {
+  const leftovers = entries ?? (await findScriptMarkers(ctx, scriptId));
+
+  for (const entry of leftovers) {
+    try {
+      await ctx.objects.deleteScriptMarker(entry);
+      ctx.log.result(`cleaned  ${entry.id}`);
+    } catch (err) {
+      ctx.log.warn(`Could not remove the leftover state ${entry.id}: ${reason(err)}`);
+    }
+  }
+}
+
 /**
  * Backs up a script object to the trash directory before it is destroyed.
  * Returns the path it was written to, and throws if the write fails — callers
@@ -32,6 +99,7 @@ export async function remove(
   opts: { yes?: boolean; deleteLocal?: boolean },
 ): Promise<void> {
   const scriptObj = await ctx.objects.getScript(id);
+  const leftovers = await findScriptMarkers(ctx, id);
   const manifest = await loadManifest(ctx.root, (m) => {
     ctx.log.warn(m);
   });
@@ -43,6 +111,9 @@ export async function remove(
     if (!scriptObj) {
       ctx.log.info('  (not found on the server — nothing to delete there)');
     }
+    for (const state of leftovers) {
+      ctx.log.info(`Would clean up leftover:     ${state.id}`);
+    }
     if (opts.deleteLocal && localPath) {
       ctx.log.info(`Would delete local file:     ${localPath}`);
     } else if (localPath) {
@@ -53,10 +124,29 @@ export async function remove(
   }
 
   if (!scriptObj) {
-    throw new UserError(
-      `Script "${id}" was not found on the server.`,
-      'Run `iob-sync list` to see the available script ids.',
-    );
+    // Already gone from the server, but its markers are not: sweeping them is the
+    // whole remaining job. Refusing here would leave the user with a warning they
+    // have no way to clear — this is the only command that can.
+    if (leftovers.length === 0) {
+      throw new UserError(
+        `Script "${id}" was not found on the server.`,
+        'Run `iob-sync list` to see the available script ids.',
+      );
+    }
+
+    if (ctx.dryRun) {
+      ctx.log.result(`[dry-run] clean ${leftovers.length} leftover state(s) of ${id}`);
+      return;
+    }
+
+    ctx.log.info(`"${id}" is already gone from the server — cleaning up what it left behind.`);
+    await cleanUpScriptMarkers(ctx, id, leftovers);
+    if (localPath) {
+      // No object means no backup, and a delete without a backup is not something
+      // this command does — invariant or not, the file is the last copy.
+      ctx.log.info(`kept     ${localPath} (the server had nothing left to back up)`);
+    }
+    return;
   }
 
   if (ctx.dryRun) {
@@ -79,6 +169,11 @@ export async function remove(
   await ctx.objects.deleteObject(id);
   ctx.log.result(`remove   ${id}`);
 
+  // Re-read rather than reusing the list from before the delete: the owning instance
+  // reacts to the object disappearing by removing its own marker, and whichever of us
+  // gets there first, what is left afterwards is exactly what nobody is coming back for.
+  await cleanUpScriptMarkers(ctx, id);
+
   if (opts.deleteLocal && localPath) {
     try {
       await fs.unlink(localPath);
diff --git a/src/commands/rename.ts b/src/commands/rename.ts
index 4146748..5ca5bfe 100644
--- a/src/commands/rename.ts
+++ b/src/commands/rename.ts
@@ -3,7 +3,7 @@ import * as path from 'node:path';
 import { CommandContext, UserError, ScriptObject } from '../types';
 import { idToRelPath, normalizeSource } from '../sync/mapping';
 import { loadManifest, saveManifest, removeEntry, upsertEntry } from '../sync/manifest';
-import { backupObject } from './remove';
+import { backupObject, cleanUpScriptMarkers } from './remove';
 
 /**
  * Sanitizes a single id segment: space, any remaining `.`, and the characters
@@ -60,6 +60,11 @@ export async function copyVerifyAndDelete(
   const backupPath = await backupObject(ctx, original);
   ctx.log.info(`backup   ${backupPath}`);
   await ctx.objects.deleteObject(original._id);
+
+  // The old id keeps its `scriptEnabled` markers unless someone removes them, and a
+  // rename that quietly leaves one behind every time it runs is how a system ends up
+  // with more markers than scripts.
+  await cleanUpScriptMarkers(ctx, original._id);
 }
 
 export async function rename(
diff --git a/src/types.ts b/src/types.ts
index f0b7fbc..24190be 100644
--- a/src/types.ts
+++ b/src/types.ts
@@ -97,6 +97,44 @@ export interface ObjectViewResult<T> {
   rows: { id: string; value: T }[];
 }
 
+/**
+ * The two per-script bookkeeping states the javascript adapter maintains.
+ *
+ * They are created together by `load()` and deleted together in the same block, so
+ * anything that treats one without the other cleans up half a mess and reports
+ * success — verified the hard way against a live instance, which had eight orphaned
+ * `scriptProblem` states while reporting zero orphaned `scriptEnabled` ones.
+ */
+export const MARKER_KINDS = ['scriptEnabled', 'scriptProblem'] as const;
+
+export type MarkerKind = (typeof MARKER_KINDS)[number];
+
+/**
+ * One `javascript.<n>.<kind>.<suffix>` entry — per-script bookkeeping the javascript
+ * adapter keeps beside every script, on every instance.
+ *
+ * Every instance creates both markers for every non-global script, because `load()`
+ * calls `createActiveObject`/`createProblemObject` before `prepareScript` checks
+ * whether this instance actually owns the script (verified in ioBroker.javascript
+ * v8.9.2, both at startup and on every source change). Only the owning instance ever
+ * deletes them again, so each delete strands one pair per other instance.
+ *
+ * Both halves are tracked separately because they rot apart. `hasValue && !hasObject`
+ * is the combination js-controller warns about on every restart, and the adapter
+ * itself can produce it: its cleanup calls `delObject` before `delState`.
+ */
+export interface ScriptMarkerEntry {
+  /** e.g. "javascript.2.scriptEnabled.common.garage". */
+  id: string;
+  /** The script it belongs to, e.g. "script.js.common.garage". */
+  scriptId: string;
+  kind: MarkerKind;
+  /** A value is stored under this id. */
+  hasValue: boolean;
+  /** An object is defined for this id. */
+  hasObject: boolean;
+}
+
 // ---------------------------------------------------------------------------
 // Transport
 // ---------------------------------------------------------------------------
@@ -194,6 +232,21 @@ export interface ObjectsApi {
   ensureFolders(scriptId: string): Promise<string[]>;
   /** Delete an object. Callers must have obtained explicit confirmation and written a backup. */
   deleteObject(id: string): Promise<void>;
+  /**
+   * Every script marker on the instance — both kinds, across all javascript instances.
+   *
+   * Deliberately unfiltered: callers narrow by `scriptId` themselves. Building a
+   * server-side pattern out of a script id would mean interpolating an id into a
+   * wildcard expression, and the one thing that must never happen here is a delete
+   * loop running against a pattern that matched more than it was meant to.
+   */
+  listScriptMarkers(): Promise<ScriptMarkerEntry[]>;
+  /**
+   * Delete one marker: the value first, then the object. Never the other way round —
+   * an object deleted out from under a surviving value is precisely the state that
+   * makes js-controller warn forever.
+   */
+  deleteScriptMarker(entry: ScriptMarkerEntry): Promise<void>;
 }
 
 // ---------------------------------------------------------------------------
diff --git a/test/commands-destructive.test.ts b/test/commands-destructive.test.ts
index 4bfe3ae..1447d8b 100644
--- a/test/commands-destructive.test.ts
+++ b/test/commands-destructive.test.ts
@@ -321,3 +321,180 @@ describe('destructive commands', () => {
     assert.deepEqual(await listTrash(project.root), []);
   });
 });
+
+/**
+ * Every javascript instance that runs a script keeps a `scriptEnabled` marker beside
+ * it, and ioBroker only ever cleans up the one belonging to the instance that owned the
+ * script at the moment it was deleted. Anything left behind is invisible to the user and
+ * complained about by js-controller forever, so the delete paths sweep it themselves.
+ */
+describe('script marker cleanup', () => {
+  let server: FakeAdminServer;
+  let port: number;
+  let project: TempProject;
+
+  const TARGET = 'script.js.common.target';
+  const OWN_MARKER = 'javascript.2.scriptEnabled.common.target';
+  // Held by an instance that does not run the script — the pair ioBroker never cleans.
+  const STALE_MARKER = 'javascript.1.scriptEnabled.common.target';
+  // The twin the adapter creates beside every scriptEnabled state, and the one the
+  // first version of this sweep missed on a real instance.
+  const STALE_PROBLEM = 'javascript.1.scriptProblem.common.target';
+  const OTHER_MARKER = 'javascript.2.scriptEnabled.other';
+
+  before(async () => {
+    server = new FakeAdminServer();
+    port = await server.start();
+  });
+
+  after(async () => {
+    await server.stop();
+  });
+
+  beforeEach(async () => {
+    server.reset();
+    server.seed([script(TARGET), script('script.js.other')]);
+    server.seedMarker(OWN_MARKER, true);
+    server.seedMarker(STALE_MARKER, true);
+    server.seedMarker(STALE_PROBLEM, false);
+    server.seedMarker(OTHER_MARKER, true);
+    if (project) await project.cleanup();
+    project = await makeTempProject();
+    await writeLocal(project, 'common/target.ts', SOURCE);
+    await writeManifest(project.root, [
+      entryFor(TARGET, 'common/target.ts', 'TypeScript/ts', SOURCE),
+    ]);
+  });
+
+  it('remove --yes sweeps the markers of the deleted script and nothing else', async () => {
+    const t = await makeContext(port, project);
+    await remove(t.ctx, TARGET, { yes: true });
+    await t.close();
+
+    assert.equal(server.getObject(TARGET), null);
+    assert.deepEqual(server.stateIds(), [OTHER_MARKER], 'only the other script keeps its marker');
+    assert.equal(server.getObject(OWN_MARKER), null, 'the marker object goes too');
+    assert.equal(server.getObject(STALE_MARKER), null);
+    assert.equal(server.getObject(STALE_PROBLEM), null, 'the scriptProblem twin goes too');
+    assert.ok(t.captured.result.some((l) => l === `cleaned  ${STALE_MARKER}`));
+    assert.ok(t.captured.result.some((l) => l === `cleaned  ${STALE_PROBLEM}`));
+  });
+
+  /**
+   * Guards the specific regression: sweeping only `scriptEnabled` left the
+   * `scriptProblem` twin behind on a live instance while reporting success.
+   */
+  it('leaves no scriptProblem state behind when the scriptEnabled one is swept', async () => {
+    const t = await makeContext(port, project);
+    await remove(t.ctx, TARGET, { yes: true });
+    await t.close();
+
+    assert.deepEqual(
+      server.stateIds().filter((id) => id.includes('common.target')),
+      [],
+      'no marker of either kind may survive for the deleted script',
+    );
+  });
+
+  it('remove without --yes lists the markers and deletes nothing', async () => {
+    const t = await makeContext(port, project);
+    await remove(t.ctx, TARGET, {});
+    await t.close();
+
+    assert.deepEqual(
+      server.stateIds(),
+      [STALE_MARKER, STALE_PROBLEM, OWN_MARKER, OTHER_MARKER].sort(),
+    );
+    assert.ok(
+      t.captured.all.some((l) => l.includes(`Would clean up leftover:     ${STALE_MARKER}`)),
+    );
+  });
+
+  /**
+   * The case that makes the doctor report actionable: the script was deleted long ago,
+   * from the Admin UI or by another tool, and only the markers remain. Refusing here
+   * would leave the user with a warning nothing can clear.
+   */
+  it('remove --yes cleans markers of a script that is already gone from the server', async () => {
+    const t = await makeContext(port, project);
+    await remove(t.ctx, TARGET, { yes: true });
+    // Second run: the object is gone, the markers are back (as if never swept).
+    server.seedMarker(STALE_MARKER, true);
+    await remove(t.ctx, TARGET, { yes: true });
+    await t.close();
+
+    assert.deepEqual(server.stateIds(), [OTHER_MARKER]);
+    assert.ok(t.captured.all.some((l) => l.includes('already gone from the server')));
+    assert.ok(
+      await localExists(project, 'common/target.ts'),
+      'the local file is never touched here',
+    );
+  });
+
+  it('remove --yes still refuses an id with neither a script nor any markers', async () => {
+    const t = await makeContext(port, project);
+    await assert.rejects(() => remove(t.ctx, 'script.js.nothing-here', { yes: true }), UserError);
+    await t.close();
+  });
+
+  it('remove --dry-run does not sweep markers of an already-deleted script', async () => {
+    // Rebuild the world without the script, so the already-gone path is the one taken.
+    server.reset();
+    server.seedMarker(STALE_MARKER, true);
+    const t = await makeContext(port, project, { dryRun: true });
+    await remove(t.ctx, TARGET, { yes: true });
+    await t.close();
+
+    assert.ok(server.getState(STALE_MARKER), 'dry-run must not delete anything');
+  });
+
+  it('rename --yes sweeps the markers of the old id', async () => {
+    const t = await makeContext(port, project);
+    await rename(t.ctx, TARGET, 'renamed', { yes: true });
+    await t.close();
+
+    assert.ok(server.getObject('script.js.common.renamed'), 'the rename itself must have worked');
+    assert.deepEqual(server.stateIds(), [OTHER_MARKER]);
+  });
+
+  it('move --yes sweeps the markers of the old id', async () => {
+    server.seed([
+      { _id: 'script.js.archive', type: 'channel', common: { name: 'archive' }, native: {} },
+    ]);
+    const t = await makeContext(port, project);
+    await move(t.ctx, TARGET, 'archive', { yes: true });
+    await t.close();
+
+    assert.ok(server.getObject('script.js.archive.target'));
+    assert.deepEqual(server.stateIds(), [OTHER_MARKER]);
+  });
+
+  /**
+   * The script is already deleted and backed up by the time the sweep runs, so a
+   * failure here is untidiness, not data loss. Reporting it as a failed delete would
+   * be worse than the leftover it is complaining about.
+   */
+  it('a marker that cannot be deleted warns but does not fail the command', async () => {
+    server.failCommand('delState', 'states db is read-only');
+    const t = await makeContext(port, project);
+    await remove(t.ctx, TARGET, { yes: true });
+    await t.close();
+
+    assert.equal(server.getObject(TARGET), null, 'the script itself is still deleted');
+    assert.equal((await listTrash(project.root)).length, 1, 'and still backed up');
+    assert.ok(t.captured.warn.some((l) => l.includes('Could not remove the leftover state')));
+    assert.ok(server.getObject(STALE_MARKER), 'and the marker was left whole, not half-deleted');
+  });
+
+  it('a scriptEnabled lookup that fails does not stop the delete', async () => {
+    server.failCommand('getStates', 'nope');
+    server.failCommand('getForeignStates', 'nope');
+    server.failCommand('getForeignObjects', 'nope');
+    const t = await makeContext(port, project);
+    await remove(t.ctx, TARGET, { yes: true });
+    await t.close();
+
+    assert.equal(server.getObject(TARGET), null);
+    assert.equal((await listTrash(project.root)).length, 1);
+  });
+});
diff --git a/test/commands-doctor.test.ts b/test/commands-doctor.test.ts
index c067748..adfa93b 100644
--- a/test/commands-doctor.test.ts
+++ b/test/commands-doctor.test.ts
@@ -108,7 +108,7 @@ describe('doctor', () => {
       const { captured, error } = await run(project.root, config());
 
       assert.equal(error, undefined);
-      for (const name of ['config', 'tls', 'auth', 'socket', 'round-trip', 'scripts']) {
+      for (const name of ['config', 'tls', 'auth', 'socket', 'round-trip', 'scripts', 'markers']) {
         assert.equal(statusOf(captured, name), 'ok', `${name} should have passed`);
       }
       assert.ok(captured.result.includes('OK.'));
@@ -128,11 +128,87 @@ describe('doctor', () => {
 
       const checks = captured.data.filter((d) => (d as { type?: string }).type === 'check');
       const verdicts = captured.data.filter((d) => (d as { type?: string }).type === 'doctor');
-      assert.equal(checks.length, 6);
+      assert.equal(checks.length, 7);
       assert.deepEqual(verdicts, [{ type: 'doctor', ok: true, failed: 0, notes: [] }]);
     });
   });
 
+  describe('script markers', () => {
+    it('says so plainly when there is nothing left lying around', async () => {
+      const { captured } = await run(project.root, config());
+
+      assert.equal(statusOf(captured, 'markers'), 'ok');
+      assert.match(detailOf(captured, 'markers'), /0 scriptEnabled\/scriptProblem.*0 orphaned/);
+    });
+
+    it('counts markers of live scripts without flagging them', async () => {
+      // defaultSeed() has script.js.common.garage on javascript.1.
+      server.seedMarker('javascript.1.scriptEnabled.common.garage', true);
+      server.seedMarker('javascript.1.scriptProblem.common.garage', false);
+
+      const { captured } = await run(project.root, config());
+
+      assert.equal(statusOf(captured, 'markers'), 'ok');
+      assert.match(detailOf(captured, 'markers'), /2 scriptEnabled\/scriptProblem.*0 orphaned/);
+    });
+
+    /**
+     * The condition the whole check exists for: a deleted script whose markers stayed
+     * behind on the instances that did not own it — including the `scriptProblem` twin,
+     * which an earlier version of this check ignored while reporting zero orphans.
+     */
+    it('warns about markers whose script no longer exists, and names them', async () => {
+      server.seedMarker('javascript.1.scriptEnabled.common.garage', true);
+      server.seedMarker('javascript.3.scriptEnabled.diag.retired-check', true);
+      server.seedMarker('javascript.2.scriptEnabled.diag.retired-check', true, {
+        valueOnly: true,
+      });
+
+      const { captured, error } = await run(project.root, config());
+
+      assert.equal(statusOf(captured, 'markers'), 'warn');
+      assert.match(detailOf(captured, 'markers'), /3 scriptEnabled\/scriptProblem.*2 orphaned/);
+
+      const note = detailOf(captured, 'markers');
+      assert.match(note, /javascript\.2\.scriptEnabled\.diag\.retired-check/);
+      assert.match(note, /javascript\.3\.scriptEnabled\.diag\.retired-check/);
+      assert.doesNotMatch(note, /javascript\.1\./, 'a live script must not be listed');
+      // The half-rotted one is the one js-controller actually complains about.
+      assert.match(note, /1 of them is a value with no object behind them/);
+      assert.match(note, /iob-sync remove script\.js\.diag\.retired-check --yes/);
+
+      // A warning, not a failure: nothing here is broken.
+      assert.equal(error, undefined);
+      assert.ok(captured.result.includes('OK with notes.'));
+    });
+
+    it('counts an orphaned scriptProblem state even when its scriptEnabled twin is gone', async () => {
+      // Exactly the state a live instance was left in by a sweep that knew only one kind.
+      server.seedMarker('javascript.2.scriptProblem.diag.retired-check', false);
+
+      const { captured } = await run(project.root, config());
+
+      assert.equal(statusOf(captured, 'markers'), 'warn');
+      assert.match(detailOf(captured, 'markers'), /1 scriptEnabled\/scriptProblem.*1 orphaned/);
+      assert.match(
+        detailOf(captured, 'markers'),
+        /javascript\.2\.scriptProblem\.diag\.retired-check/,
+      );
+    });
+
+    it('does not fail the whole diagnostic when the markers cannot be read', async () => {
+      server.failCommand('getStates', 'nope');
+      server.failCommand('getForeignStates', 'nope');
+      server.failCommand('getForeignObjects', 'nope');
+
+      const { captured, error } = await run(project.root, config());
+
+      assert.equal(statusOf(captured, 'markers'), 'warn');
+      assert.equal(statusOf(captured, 'scripts'), 'ok');
+      assert.equal(error, undefined);
+    });
+  });
+
   describe('a socket that is open but not authenticated', () => {
     it('names the cause instead of reporting a bare timeout', async () => {
       // Auth stays "disabled" over HTTP, so no cookie is fetched — exactly what
@@ -165,6 +241,7 @@ describe('doctor', () => {
       const { captured } = await run(project.root, config());
 
       assert.equal(statusOf(captured, 'scripts'), 'skip');
+      assert.equal(statusOf(captured, 'markers'), 'skip');
     });
   });
 
@@ -175,7 +252,7 @@ describe('doctor', () => {
       const { captured, error } = await run(project.root, config({ username: 'admin' }));
 
       assert.equal(statusOf(captured, 'auth'), 'fail');
-      for (const name of ['socket', 'round-trip', 'scripts']) {
+      for (const name of ['socket', 'round-trip', 'scripts', 'markers']) {
         assert.equal(statusOf(captured, name), 'skip', `${name} was not knowable`);
       }
       assert.match(String(error?.hint), /iob-sync login/);
diff --git a/test/fake-server.ts b/test/fake-server.ts
index c8833e8..bc1e50f 100644
--- a/test/fake-server.ts
+++ b/test/fake-server.ts
@@ -154,11 +154,23 @@ function deepMerge(
   return dest;
 }
 
+/** ioBroker id pattern (`javascript.*.scriptEnabled.*`) as a regex. `*` is the only wildcard. */
+function patternToRegExp(pattern: string): RegExp {
+  const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*');
+  return new RegExp(`^${escaped}$`);
+}
+
 export class FakeAdminServer {
   private wss: WebSocket.Server | null = null;
   private httpServer: http.Server | null = null;
   private readonly sockets = new Set<WebSocket>();
   private readonly objects = new Map<string, IoBrokerObject>();
+  /**
+   * State *values*, stored independently of `objects` — which is the entire point.
+   * In a real ioBroker the states DB and the objects DB are separate, and a value
+   * outliving its object is both possible and the condition this suite has to cover.
+   */
+  private readonly states = new Map<string, { val: unknown; ack: boolean }>();
   private readonly failCommands = new Map<string, string>();
   private readonly delayedCommands = new Map<string, number>();
   private corruptNextSetObjectFn: ((obj: IoBrokerObject) => IoBrokerObject) | null = null;
@@ -370,12 +382,50 @@ export class FakeAdminServer {
     }
   }
 
+  /**
+   * Real Admin's `delState` removes the object along with the value. Older builds do
+   * not, and `AdminObjectsApi.deleteScriptMarker` is written to cope with either, so
+   * the fake can be put into either mode.
+   */
+  delStateAlsoDeletesObject = true;
+
   seed(objects: IoBrokerObject[]): void {
     for (const obj of objects) {
       this.objects.set(obj._id, obj);
     }
   }
 
+  /**
+   * Seeds a `scriptEnabled` marker the way the javascript adapter writes one: a state
+   * object plus a boolean value. `objectOnly`/`valueOnly` create the half-rotted forms.
+   */
+  seedMarker(
+    id: string,
+    val: unknown = true,
+    opts: { objectOnly?: boolean; valueOnly?: boolean } = {},
+  ): void {
+    if (!opts.valueOnly) {
+      this.objects.set(id, {
+        _id: id,
+        type: 'state',
+        common: { name: id, type: 'boolean', role: 'indicator.state' },
+        native: {},
+      } as unknown as IoBrokerObject);
+    }
+    if (!opts.objectOnly) {
+      this.states.set(id, { val, ack: true });
+    }
+  }
+
+  getState(id: string): { val: unknown; ack: boolean } | null {
+    return this.states.get(id) ?? null;
+  }
+
+  /** Ids of every stored state value, sorted. */
+  stateIds(): string[] {
+    return Array.from(this.states.keys()).sort();
+  }
+
   /**
    * Clears the object store and any one-shot knobs. Tests that share a server
    * instance must call this between cases — `seed()` merges rather than replaces,
@@ -383,6 +433,8 @@ export class FakeAdminServer {
    */
   reset(): void {
     this.objects.clear();
+    this.states.clear();
+    this.delStateAlsoDeletesObject = true;
     this.corruptNextSetObjectFn = null;
     this.failCommands.clear();
     this.delayedCommands.clear();
@@ -559,6 +611,41 @@ export class FakeAdminServer {
         return;
       }
 
+      // `getForeignStates` is the deprecated alias real Admin still answers; the client
+      // falls back to it, so the fake has to be able to be the instance where only it works.
+      case 'getStates':
+      case 'getForeignStates': {
+        const [pattern] = args as [string];
+        const match = patternToRegExp(pattern ?? '*');
+        const out: Record<string, unknown> = Object.create(null);
+        for (const [stateId, value] of this.states) {
+          if (match.test(stateId)) out[stateId] = value;
+        }
+        this.reply(ws, id, null, out);
+        return;
+      }
+
+      case 'getForeignObjects': {
+        const [pattern, type] = args as [string, string | undefined];
+        const match = patternToRegExp(pattern ?? '*');
+        const out: Record<string, unknown> = Object.create(null);
+        for (const [objId, obj] of this.objects) {
+          if (match.test(objId) && (!type || obj.type === type)) out[objId] = obj;
+        }
+        this.reply(ws, id, null, out);
+        return;
+      }
+
+      case 'delState': {
+        const [stateId] = args as [string];
+        this.states.delete(stateId);
+        if (this.delStateAlsoDeletesObject) {
+          this.objects.delete(stateId);
+        }
+        this.reply(ws, id, null, null);
+        return;
+      }
+
       case 'subscribeObjects':
       case 'unsubscribeObjects': {
         // No server-side subscription bookkeeping needed for the fake: object
diff --git a/test/objects.test.ts b/test/objects.test.ts
index d1875a0..349d569 100644
--- a/test/objects.test.ts
+++ b/test/objects.test.ts
@@ -239,3 +239,229 @@ describe('AdminObjectsApi: deleteObject', () => {
     });
   });
 });
+
+describe('AdminObjectsApi: script markers', () => {
+  /**
+   * Mirrors a real instance: every instance holds markers for scripts it does not run,
+   * `gone` has no script left at all, and each script carries a `scriptProblem` twin
+   * alongside its `scriptEnabled` one.
+   */
+  function seedMarkers(server: FakeAdminServer): void {
+    server.seedMarker('javascript.1.scriptEnabled.common.garage', true);
+    server.seedMarker('javascript.3.scriptEnabled.common.garage', false);
+    server.seedMarker('javascript.2.scriptEnabled.diag.gone', true);
+    // Not a marker: same namespace, different purpose. Must never be picked up.
+    server.seedMarker('javascript.0.variables.someUserState', 42);
+    // Nor is this: right shape, but the instance is not a number.
+    server.seedMarker('javascript.admin.scriptEnabled.nope', true);
+  }
+
+  test('lists markers across instances and ignores other javascript states', async () => {
+    await withApi(async (api, server) => {
+      seedMarkers(server);
+      const entries = await api.listScriptMarkers();
+
+      assert.deepEqual(
+        entries.map((e) => e.id),
+        [
+          'javascript.1.scriptEnabled.common.garage',
+          'javascript.2.scriptEnabled.diag.gone',
+          'javascript.3.scriptEnabled.common.garage',
+        ],
+      );
+      assert.deepEqual(
+        entries.map((e) => e.scriptId),
+        ['script.js.common.garage', 'script.js.diag.gone', 'script.js.common.garage'],
+      );
+      assert.ok(entries.every((e) => e.hasValue && e.hasObject));
+    });
+  });
+
+  test('reports each half of a marker separately', async () => {
+    await withApi(async (api, server) => {
+      server.seedMarker('javascript.1.scriptEnabled.a', true, { valueOnly: true });
+      server.seedMarker('javascript.2.scriptEnabled.b', true, { objectOnly: true });
+
+      const entries = await api.listScriptMarkers();
+      const byId = new Map(entries.map((e) => [e.id, e]));
+
+      assert.deepEqual(
+        { ...byId.get('javascript.1.scriptEnabled.a') },
+        {
+          id: 'javascript.1.scriptEnabled.a',
+          scriptId: 'script.js.a',
+          kind: 'scriptEnabled',
+          hasValue: true,
+          hasObject: false,
+        },
+      );
+      assert.deepEqual(
+        { ...byId.get('javascript.2.scriptEnabled.b') },
+        {
+          id: 'javascript.2.scriptEnabled.b',
+          scriptId: 'script.js.b',
+          kind: 'scriptEnabled',
+          hasValue: false,
+          hasObject: true,
+        },
+      );
+    });
+  });
+
+  test('falls back to getForeignStates on an instance without getStates', async () => {
+    await withApi(async (api, server) => {
+      seedMarkers(server);
+      server.failCommand('getStates', 'Unknown command: getStates');
+
+      const entries = await api.listScriptMarkers();
+      assert.equal(entries.length, 3);
+      assert.ok(entries.every((e) => e.hasValue));
+    });
+  });
+
+  test('still reports markers when the object side cannot be read', async () => {
+    await withApi(async (api, server) => {
+      seedMarkers(server);
+      server.failCommand('getForeignObjects', 'permission denied');
+
+      const entries = await api.listScriptMarkers();
+      assert.equal(entries.length, 3);
+      assert.ok(entries.every((e) => e.hasValue && !e.hasObject));
+    });
+  });
+
+  test('deleteScriptMarker removes the value and the object', async () => {
+    await withApi(async (api, server) => {
+      seedMarkers(server);
+      const id = 'javascript.2.scriptEnabled.diag.gone';
+      const entry = (await api.listScriptMarkers()).find((e) => e.id === id)!;
+
+      await api.deleteScriptMarker(entry);
+
+      assert.equal(server.getState(id), null, 'the value must be gone');
+      assert.equal(server.getObject(id), null, 'the object must be gone');
+      assert.ok(server.getState('javascript.1.scriptEnabled.common.garage'), 'others untouched');
+    });
+  });
+
+  test('deletes the object separately where delState leaves it behind', async () => {
+    await withApi(async (api, server) => {
+      seedMarkers(server);
+      // The behaviour of older Admin builds: the value goes, the object stays.
+      server.delStateAlsoDeletesObject = false;
+      const id = 'javascript.2.scriptEnabled.diag.gone';
+      const entry = (await api.listScriptMarkers()).find((e) => e.id === id)!;
+
+      await api.deleteScriptMarker(entry);
+
+      assert.equal(server.getState(id), null);
+      assert.equal(server.getObject(id), null, 'the follow-up delObject must have run');
+    });
+  });
+
+  /**
+   * The failure mode that matters: deleting the object while the value survives is
+   * what produces the "state has no object" warning in the first place. A delState
+   * that fails must abort before that can happen.
+   */
+  test('a failed value delete leaves the object alone rather than orphaning it', async () => {
+    await withApi(async (api, server) => {
+      seedMarkers(server);
+      const id = 'javascript.2.scriptEnabled.diag.gone';
+      const entry = (await api.listScriptMarkers()).find((e) => e.id === id)!;
+      server.failCommand('delState', 'states db is read-only');
+
+      await assert.rejects(() => api.deleteScriptMarker(entry));
+
+      assert.ok(server.getState(id), 'the value is still there');
+      assert.ok(server.getObject(id), 'so the object must be too');
+    });
+  });
+
+  test('refuses an id outside the marker namespaces', async () => {
+    await withApi(async (api, server) => {
+      server.seedMarker('javascript.0.variables.someUserState', 42);
+
+      await assert.rejects(
+        () =>
+          api.deleteScriptMarker({
+            id: 'javascript.0.variables.someUserState',
+            scriptId: 'script.js.someUserState',
+            kind: 'scriptEnabled',
+            hasValue: true,
+            hasObject: true,
+          }),
+        /Refusing to delete/,
+      );
+      assert.ok(server.getState('javascript.0.variables.someUserState'));
+    });
+  });
+
+  /**
+   * The defect a live instance caught: the adapter creates `scriptEnabled` and
+   * `scriptProblem` together and deletes them together, so anything that handles only
+   * the first cleans up half a mess and reports success.
+   */
+  test('lists scriptProblem states alongside scriptEnabled ones', async () => {
+    await withApi(async (api, server) => {
+      server.seedMarker('javascript.1.scriptEnabled.diag.gone', true);
+      server.seedMarker('javascript.1.scriptProblem.diag.gone', false);
+      server.seedMarker('javascript.2.scriptProblem.diag.gone', false);
+
+      const entries = await api.listScriptMarkers();
+
+      assert.deepEqual(
+        entries.map((e) => `${e.kind} ${e.id}`),
+        [
+          'scriptEnabled javascript.1.scriptEnabled.diag.gone',
+          'scriptProblem javascript.1.scriptProblem.diag.gone',
+          'scriptProblem javascript.2.scriptProblem.diag.gone',
+        ],
+      );
+      assert.ok(
+        entries.every((e) => e.scriptId === 'script.js.diag.gone'),
+        'both kinds must map back to the same script',
+      );
+    });
+  });
+
+  /**
+   * A script may legitimately be *named* after a marker kind, which puts the infix in the
+   * id twice. Only the leading occurrence, right after a numeric instance, identifies the
+   * marker; the rest belongs to the script name. Getting this backwards would map a state
+   * onto the wrong script — the one mistake here that could delete something real.
+   */
+  test('maps an id whose script name contains a marker kind back to the right script', async () => {
+    await withApi(async (api, server) => {
+      server.seedMarker('javascript.1.scriptProblem.foo.scriptEnabled.bar', false);
+
+      const entries = await api.listScriptMarkers();
+
+      assert.equal(entries.length, 1);
+      assert.deepEqual(
+        { ...entries[0] },
+        {
+          id: 'javascript.1.scriptProblem.foo.scriptEnabled.bar',
+          scriptId: 'script.js.foo.scriptEnabled.bar',
+          kind: 'scriptProblem',
+          hasValue: true,
+          hasObject: true,
+        },
+      );
+    });
+  });
+
+  test('deletes a scriptProblem state the same way', async () => {
+    await withApi(async (api, server) => {
+      const id = 'javascript.2.scriptProblem.diag.gone';
+      server.seedMarker(id, false);
+      const entry = (await api.listScriptMarkers()).find((e) => e.id === id)!;
+
+      assert.equal(entry.kind, 'scriptProblem');
+      await api.deleteScriptMarker(entry);
+
+      assert.equal(server.getState(id), null);
+      assert.equal(server.getObject(id), null);
+    });
+  });
+});