premiere-pro-mcp 1.18.4 → 1.18.5

package/CHANGELOG.md

@@ -6,6 +6,29 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [1.18.5] - 2026-09-28
+
+### Fixed
+
+- `unnest_sequence` refuses before any change when the nest is trimmed, speed-changed or reversed, a target track is locked, or the target range already holds a clip. It now overwrites each nested clip's exact source range in place instead of inserting it, which pushed later clips down the track and ignored each clip's in and out. It reads every clip back afterwards and reports "The timeline changed … Use Undo" on any mismatch. Effects, keyframes, and transitions inside the nest are not carried over; the description says so. (#642)
+- `move_clip_to_track` refuses before calling QE when either track is locked or the target range is occupied, finds the moved clip even when its node ID changes, and reports a copy left on the original track or a changed start, length, or in/out. It is now marked EXPERIMENTAL (QE) and rejects non-integer track numbers. (#642)
+- `replace_clip` overwrites exactly the old clip's start and end instead of inserting the new item, which pushed later clips down the track and used the new item's full length. It verifies the span, that the old clip is gone, and that track clip counts are unchanged, and refuses on a locked track. The old clip's linked partner is left in place; the description says so. (#642)
+- `export_frame_uxp` checks that the PNG exists after Premiere's exporter returns. It fails when no file was written, reports the real path when the host names the file differently (with or without the `.png` extension), and reports `committed_unverified` when UXP storage cannot check or the file already existed before the export. The panel's direct frame-export path now uses the same handler. (#642)
+- `encode_media_uxp` results for jobs sent to Adobe Media Encoder carry `ameQueueStarted: "unknown"` and a note. Premiere 26.5.1 accepted UXP encodes into the Media Encoder queue without starting it. The tool does not start the queue through CEP; the note points to Media Encoder or `start_batch_encode`. (#642)
+- `organize_project_items_uxp` remove verifies absence by walking the project tree instead of checking the Project panel selection first, which could still hold the removed item and turned a successful removal into `committed_unverified`. Remove now requires `project_item_id` and never falls back to the selection. (#642)
+- `refresh_media` reads the interpreted frame rate before and after the refresh. When the refresh leaves an implausible rate (reported on stills as 29.97 becoming 2.75e-8), it restores the previous rate, reads it back, and reports `repaired: true`; if the restore does not stick, it fails with the manual fix. A real rate change from the source file is kept. (#642)
+- `edit_timeline_uxp` MOGRT inserts (`insert_mogrt_path`, `insert_mogrt_library`) read the placement back instead of reporting the SequenceEditor return value. The result is `verified` when a returned item starts at the requested time, within one frame, on the requested video track. It fails with `UXP_VERIFICATION_FAILED` when nothing is there, and stays `committed_unverified` when the track cannot be read. Results include `sequenceId`, `requested`, and up to 16 `placements`. (#642)
+- `set_sequence_pixel_aspect_ratio` compares the read-back ratio as a number, so a host that formats it as `1`, `1:1`, or `1.42222` no longer fails a correct update. A real mismatch reports the value Premiere read back. (#642)
+- `play_source_monitor` fails with "No clip is loaded in the Source Monitor" instead of reporting a playback request that does nothing, names the loaded clip, and rejects a `speed` that is zero, not finite, or outside -64 to 64 before building a script. (#642)
+- `create_bars_and_tone` takes an optional `bin_id`. The bin is resolved before anything is created, the new item is moved there, and its location is read back; the result is `committed_unverified` when the move cannot be confirmed. (#642)
+- `get_unused_media` and `get_duplicate_media` page their output with `offset`, `limit` (1-500, default 100), and a case-insensitive `contains` name filter, and return `total`, `returned`, `truncated`, and `nextOffset`. Large projects no longer return unbounded lists. (#642)
+- `get_duplicate_media` no longer groups different After Effects compositions imported from the same `.aep` or `.aepx` as duplicates. The same composition imported twice is still reported. (#642)
+- `get_project_panel_metadata` caps the returned XML at `max_chars` (256-200000, default 20000) and reports `truncated` and `totalChars`. Truncated XML is marked as unsafe to pass back to `set_project_panel_metadata`. (#642)
+
+### Verification scope
+
+- Automated checks validate package behavior. These changes follow live reports from Premiere 26.5.1 but have not been re-verified on a licensed Premiere host. The `unnest_sequence` and `replace_clip` overwrite path (`Track.overwriteClip` with source In/Out marks) has only been exercised against test fakes; its readback reports any host difference as a failure.
+
 ## [1.18.4] - 2026-09-28
 
 ### Fixed

package/README.md

@@ -110,9 +110,9 @@ The current source exposes 384 core tools for supported workflow steps spanning
 
 <a id="latest-release"></a>
 
-### Latest release: 1.18.3
+### Latest release: 1.18.4
 
-The published v1.18.3 npm artifact contains **384 core tools**, 382 in its default profile,
+The published v1.18.4 npm artifact contains **384 core tools**, 382 in its default profile,
 and 478 with a compatible UXP connection. The development catalog above can include
 unreleased work. See the [versioned facts and package provenance](https://premiere-pro-mcp.com/facts/).
 
@@ -162,7 +162,7 @@ if the connection is unavailable.
   local Premiere processes. See the generated [supported action catalog](docs/supported-actions.md)
   for individual capability and verification contracts.
 
-See the [v1.18.3 release notes](https://github.com/leancoderkavy/premiere-pro-mcp/releases/tag/v1.18.3)
+See the [v1.18.4 release notes](https://github.com/leancoderkavy/premiere-pro-mcp/releases/tag/v1.18.4)
 for complete details. Live installation in Premiere Pro still requires host verification.
 
 ### Current MCP protocol support
@@ -210,7 +210,7 @@ their bins, media rules, and organization rules before a facility uses one.
 > ### Install the published package (verify the name)
 >
 > ```bash
-> npm i -g premiere-pro-mcp@1.18.3
+> npm i -g premiere-pro-mcp@1.18.4
 > ```
 >
 > This repository publishes only **`premiere-pro-mcp`**. A differently named package (`adobe-premiere-pro-mcp`) may also declare a `premiere-pro-mcp` executable. Before configuring a client, confirm:
@@ -218,7 +218,7 @@ their bins, media rules, and organization rules before a facility uses one.
 > | Check | Expected |
 > | --- | --- |
 > | Package name | `premiere-pro-mcp` (not `adobe-premiere-pro-mcp`) |
-> | Version | `1.18.3` |
+> | Version | `1.18.4` |
 > | Homepage / repo | https://premiere-pro-mcp.com/ · https://github.com/leancoderkavy/premiere-pro-mcp |
 >
 > ```bash
@@ -231,9 +231,9 @@ their bins, media rules, and organization rules before a facility uses one.
 
 ### Easiest supported path: Claude Desktop
 
-1. Download the current [Claude Desktop bundle (`.mcpb`)](https://github.com/leancoderkavy/premiere-pro-mcp/releases/download/v1.18.3/premiere-pro-mcp-1.18.3.mcpb).
+1. Download the current [Claude Desktop bundle (`.mcpb`)](https://github.com/leancoderkavy/premiere-pro-mcp/releases/download/v1.18.4/premiere-pro-mcp-1.18.4.mcpb).
 2. In Claude Desktop, open **Settings > Extensions > Advanced settings > Install Extension**, select the downloaded bundle, and restart Claude Desktop.
-3. Download the separate [signed Premiere connector (`.zxp`)](https://github.com/leancoderkavy/premiere-pro-mcp/releases/download/v1.18.3/MCPBridgeCEP.zxp). Open it with your trusted ZXP installer. If your computer has no ZXP installer, use the npm connector installer in **Advanced setup** below.
+3. Download the separate [signed Premiere connector (`.zxp`)](https://github.com/leancoderkavy/premiere-pro-mcp/releases/download/v1.18.4/MCPBridgeCEP.zxp). Open it with your trusted ZXP installer. If your computer has no ZXP installer, use the npm connector installer in **Advanced setup** below.
 4. Restart Premiere, open a project, then open **Window > Extensions > MCP for Adobe Premiere Pro**.
 5. In Claude, enter: `Safely check my Premiere connection with verify_premiere_connection. Make no changes.`
 
@@ -533,11 +533,11 @@ From a clone of this repository:
 ```bash
 codex plugin marketplace add .
 codex plugin add premiere-pro@premiere-pro-mcp
-npx -y premiere-pro-mcp@1.18.3 --install-cep
+npx -y premiere-pro-mcp@1.18.4 --install-cep
 ```
 
 Restart Premiere Pro and start a new Codex session after installation. The plugin
-launches `premiere-pro-mcp@1.18.3` through `npx`; the separate CEP installation is
+launches `premiere-pro-mcp@1.18.4` through `npx`; the separate CEP installation is
 required because the MCP server communicates with the running Premiere host through
 the local bridge.
 
@@ -575,7 +575,7 @@ For Claude Code, add this repository as a marketplace and install the plugin:
 Then install the Premiere bridge and start a new Claude Code session:
 
 ```bash
-npx -y premiere-pro-mcp@1.18.3 --install-cep
+npx -y premiere-pro-mcp@1.18.4 --install-cep
 ```
 
 The Claude Code package lives in

package/after-effects-cep-plugin/CSXS/manifest.xml

@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<ExtensionManifest Version="7.0" ExtensionBundleId="com.mcp.aftereffects.bridge" ExtensionBundleVersion="1.18.4" ExtensionBundleName="MCP for Adobe After Effects">
+<ExtensionManifest Version="7.0" ExtensionBundleId="com.mcp.aftereffects.bridge" ExtensionBundleVersion="1.18.5" ExtensionBundleName="MCP for Adobe After Effects">
   <ExtensionList>
-    <Extension Id="com.mcp.aftereffects.bridge.panel" Version="1.18.4"/>
+    <Extension Id="com.mcp.aftereffects.bridge.panel" Version="1.18.5"/>
   </ExtensionList>
   <ExecutionEnvironment>
     <HostList>

package/cep-plugin/CSXS/manifest.xml

@@ -1,8 +1,8 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<ExtensionManifest Version="7.0" ExtensionBundleId="com.mcp.premiere.bridge" ExtensionBundleVersion="1.18.4" ExtensionBundleName="MCP for Adobe Premiere Pro">
+<ExtensionManifest Version="7.0" ExtensionBundleId="com.mcp.premiere.bridge" ExtensionBundleVersion="1.18.5" ExtensionBundleName="MCP for Adobe Premiere Pro">
   <ExtensionList>
-    <Extension Id="com.mcp.premiere.bridge.panel" Version="1.18.4"/>
-    <Extension Id="com.mcp.premiere.bridge.headless" Version="1.18.4"/>
+    <Extension Id="com.mcp.premiere.bridge.panel" Version="1.18.5"/>
+    <Extension Id="com.mcp.premiere.bridge.headless" Version="1.18.5"/>
   </ExtensionList>
   <ExecutionEnvironment>
     <HostList>

package/cep-plugin/index.html

@@ -81,7 +81,7 @@
     <section class="update-section" aria-live="polite">
       <div class="update-copy">
         <span class="section-label">MCP updates</span>
-        <strong id="updateTitle">Version 1.18.4</strong>
+        <strong id="updateTitle">Version 1.18.5</strong>
         <span id="updateDetail">Checking the global MCP server and connector release…</span>
       </div>
       <button id="btnUpdate" class="button button-update" onclick="handleUpdateClick()" type="button" aria-describedby="updateDetail" disabled>

package/cep-plugin/updater.cjs

@@ -7,7 +7,7 @@
 })(this, function () {
   "use strict";
 
-  var CURRENT_VERSION = "1.18.4";
+  var CURRENT_VERSION = "1.18.5";
   var PACKAGE_NAME = "premiere-pro-mcp";
   var LATEST_PACKAGE_API = "https://registry.npmjs.org/" + PACKAGE_NAME;
   var LATEST_RELEASE_API =

package/dist/bridge/script-builder.js

@@ -72,6 +72,70 @@ function __writeClipSpan(item, startTicks, endTicks) {
   }
 }
 
+// Tick comparisons for values that round-trip through seconds (ProjectItem
+// marks take seconds). Far below one frame at any frame rate.
+var __TICK_MATCH_TOL = 16;
+
+function __isTrackLocked(track) {
+  try {
+    if (track && typeof track.isLocked === "function") return !!track.isLocked();
+  } catch (eLocked) {}
+  return false;
+}
+
+// Place exactly [inTicks, outTicks) of a project item on ONE track at
+// startTicks without rippling. Track.overwriteClip places the item's In/Out
+// range, so set those marks first and restore the item's own marks afterwards.
+// mediaType: 1 = video, 2 = audio. Callers must prove the destination range is
+// empty first; overwrite never shifts neighbours but would replace them.
+// Returns { ok, attempted, marksRestored, error }. attempted=true means the
+// overwrite call ran (or threw), so the timeline may have changed.
+function __overwriteRangeOnTrack(track, item, startTicks, inTicks, outTicks, mediaType) {
+  if (!track || typeof track.overwriteClip !== "function") {
+    return { ok: false, attempted: false, marksRestored: true, error: "Track.overwriteClip is unavailable on this Premiere build" };
+  }
+  if (!item || typeof item.getInPoint !== "function" || typeof item.getOutPoint !== "function" ||
+      typeof item.setInPoint !== "function" || typeof item.setOutPoint !== "function") {
+    return { ok: false, attempted: false, marksRestored: true, error: "Project item In/Out marks cannot be set on this Premiere build" };
+  }
+  var originalIn = null;
+  var originalOut = null;
+  try {
+    originalIn = String(item.getInPoint(mediaType).ticks);
+    originalOut = String(item.getOutPoint(mediaType).ticks);
+  } catch (eMarks) {
+    return { ok: false, attempted: false, marksRestored: true, error: "Could not read the project item's In/Out marks" };
+  }
+  function setMarks(wantIn, wantOut) {
+    var currentOut = parseFloat(item.getOutPoint(mediaType).ticks);
+    if (parseFloat(wantIn) >= currentOut) {
+      item.setOutPoint(__ticksToSeconds(wantOut), mediaType);
+      item.setInPoint(__ticksToSeconds(wantIn), mediaType);
+    } else {
+      item.setInPoint(__ticksToSeconds(wantIn), mediaType);
+      item.setOutPoint(__ticksToSeconds(wantOut), mediaType);
+    }
+    return Math.abs(parseFloat(item.getInPoint(mediaType).ticks) - parseFloat(wantIn)) <= __TICK_MATCH_TOL &&
+      Math.abs(parseFloat(item.getOutPoint(mediaType).ticks) - parseFloat(wantOut)) <= __TICK_MATCH_TOL;
+  }
+  function restore() {
+    try { return setMarks(originalIn, originalOut); } catch (eRestore) { return false; }
+  }
+  var applied = false;
+  try { applied = setMarks(inTicks, outTicks); } catch (eSet) { applied = false; }
+  if (!applied) {
+    return { ok: false, attempted: false, marksRestored: restore(), error: "Premiere did not apply the source In/Out range to project item " + item.name };
+  }
+  var at = new Time();
+  at.ticks = String(startTicks);
+  try {
+    track.overwriteClip(item, at);
+  } catch (eOverwrite) {
+    return { ok: false, attempted: true, marksRestored: restore(), error: "Track.overwriteClip rejected project item " + item.name + ": " + eOverwrite.toString() };
+  }
+  return { ok: true, attempted: true, marksRestored: restore(), error: "" };
+}
+
 function __ticksToTimecode(ticks, fps) {
   var totalSeconds = __ticksToSeconds(ticks);
   var hours = Math.floor(totalSeconds / 3600);

package/dist/tools/advanced.js

@@ -515,7 +515,9 @@ export function getAdvancedTools(bridgeOptions) {
             },
         },
         move_clip_to_track: {
-            description: "Move a clip to a different track. Uses QE DOM.",
+            description: "Move a clip to a different track of the same type, keeping its start, duration, and source in/out. EXPERIMENTAL: uses the undocumented QE DOM moveToTrack. " +
+                "Refuses without changing anything when the origin or destination track is locked or the destination range is occupied. " +
+                "Reads the timeline back: verified only when the clip is on the destination track with the same span and source range and is gone from the origin track; committed_unverified when the source range cannot be read; otherwise failure with Undo guidance.",
             parameters: {
                 type: "object",
                 properties: {
@@ -531,6 +533,9 @@ export function getAdvancedTools(bridgeOptions) {
                 required: ["node_id", "target_track_index"],
             },
             handler: async (args) => {
+                if (!Number.isSafeInteger(args.target_track_index) || args.target_track_index < 0) {
+                    return { success: false, error: "target_track_index must be a non-negative integer" };
+                }
                 const nodeId = escapeForExtendScript(args.node_id);
                 const script = buildToolScript(`
           app.enableQE();
@@ -549,6 +554,47 @@ export function getAdvancedTools(bridgeOptions) {
             return __result({ moved: false, verified: true, alreadyOnTrack: true, clipName: result.clip.name, trackIndex: result.trackIndex });
           }
 
+          // Preflight: refuse before any QE call when either track is locked or
+          // the destination range holds another clip (QE would overwrite it).
+          var originTrack = targetTracks[result.trackIndex];
+          var destTrack = targetTracks[${args.target_track_index}];
+          if (__isTrackLocked(originTrack)) {
+            return __error("Move refused; nothing was changed. Origin " + result.trackType + " track " + result.trackIndex + " is locked.");
+          }
+          if (__isTrackLocked(destTrack)) {
+            return __error("Move refused; nothing was changed. Destination " + result.trackType + " track ${args.target_track_index} is locked.");
+          }
+          var moveStart = parseFloat(result.clip.start.ticks);
+          var moveEnd = parseFloat(result.clip.end.ticks);
+          for (var oi = 0; oi < destTrack.clips.numItems; oi++) {
+            var occupant = destTrack.clips[oi];
+            var occupantStart = parseFloat(occupant.start.ticks);
+            var occupantEnd = parseFloat(occupant.end.ticks);
+            if (occupantStart < moveEnd - __TICK_MATCH_TOL && occupantEnd > moveStart + __TICK_MATCH_TOL) {
+              return __error("Move refused; nothing was changed. The destination range " + __ticksToSeconds(moveStart) + "s-" + __ticksToSeconds(moveEnd) + "s on " + result.trackType + " track ${args.target_track_index} is already occupied by " + occupant.name + ", and moving there would overwrite it.");
+            }
+          }
+          var movedName = result.clip.name;
+          var movedSourceId = "";
+          try { movedSourceId = result.clip.projectItem ? String(result.clip.projectItem.nodeId) : ""; } catch (eMovedSource) {}
+
+          // Premiere can mint a new node ID when a clip changes track, so fall
+          // back to matching the same source item, name, and start on a track.
+          function findMovedOn(trackIndex) {
+            var track = targetTracks[trackIndex];
+            for (var fi = 0; fi < track.clips.numItems; fi++) {
+              var cand = track.clips[fi];
+              if (String(cand.nodeId) === "${nodeId}") return { clip: cand, trackIndex: trackIndex, trackType: result.trackType };
+              var candSource = "";
+              try { candSource = cand.projectItem ? String(cand.projectItem.nodeId) : ""; } catch (eCandSource) {}
+              if (movedSourceId && candSource === movedSourceId && cand.name === movedName &&
+                  Math.abs(parseFloat(cand.start.ticks) - moveStart) <= __TICK_MATCH_TOL) {
+                return { clip: cand, trackIndex: trackIndex, trackType: result.trackType };
+              }
+            }
+            return null;
+          }
+
           var qeTrack = result.trackType === "video"
             ? qeSeq.getVideoTrackAt(result.trackIndex)
             : qeSeq.getAudioTrackAt(result.trackIndex);
@@ -586,41 +632,64 @@ export function getAdvancedTools(bridgeOptions) {
 
           // QE reports nothing useful on success, so confirm against the DOM.
           var after = __findClip("${nodeId}");
-          if (!after) return __error("Clip ${nodeId} could not be found after the track move; the timeline may be in an unexpected state.");
+          if (!after) after = findMovedOn(${args.target_track_index});
+          if (!after) return __error("The timeline changed: clip " + movedName + " could not be found on its original or destination track after the track move. Use Undo and check the timeline.");
           if (after.trackIndex !== ${args.target_track_index}) {
+            if (findMovedOn(${args.target_track_index})) {
+              return __error("The timeline changed: Premiere placed a copy of " + movedName + " on track ${args.target_track_index} but the original is still on track " + after.trackIndex + ". Use Undo and move the clip in the Premiere UI.");
+            }
             return __error("Premiere accepted the moveToTrack call but the clip is still on track " + after.trackIndex + " rather than ${args.target_track_index}. Structural QE edits are known to no-op on some Premiere Pro 26.x installations (confirmed on 26.2.2).");
           }
+          if (findMovedOn(result.trackIndex)) {
+            return __error("The timeline changed: " + movedName + " now exists on both track " + result.trackIndex + " and track ${args.target_track_index}. Use Undo and move the clip in the Premiere UI.");
+          }
           // moveToTrack can rewrite end independently of start (#550). Re-assert
           // the original span before verifying, then fail closed if it did not hold.
           if (String(after.clip.start.ticks) !== beforeMoveStartTicks || String(after.clip.end.ticks) !== beforeMoveEndTicks) {
             try {
               __writeClipSpan(after.clip, beforeMoveStartTicks, beforeMoveEndTicks);
             } catch (spanErr) {
-              return __error("Premiere changed the clip's timeline range during the track move and it could not be restored (" + spanErr.toString() + "). Use Undo and retry in the Premiere UI.");
+              return __error("The timeline changed: Premiere changed the clip's timeline range during the track move and it could not be restored (" + spanErr.toString() + "). Use Undo and retry in the Premiere UI.");
             }
-            after = __findClip("${nodeId}");
-            if (!after) return __error("Clip ${nodeId} could not be found after restoring its timeline range; the timeline may be in an unexpected state.");
+            var restored = __findClip("${nodeId}");
+            after = restored || findMovedOn(${args.target_track_index});
+            if (!after) return __error("The timeline changed: clip " + movedName + " could not be found after restoring its timeline range. Use Undo and check the timeline.");
           }
           var afterMoveStartTicks = String(after.clip.start.ticks);
           var afterMoveEndTicks = String(after.clip.end.ticks);
           if (parseFloat(afterMoveStartTicks) >= parseFloat(afterMoveEndTicks)) {
-            return __error("Premiere left clip ${nodeId} with an inverted or empty timeline range after the track move. Use Undo and retry in the Premiere UI.");
+            return __error("The timeline changed: Premiere left clip " + movedName + " with an inverted or empty timeline range after the track move. Use Undo and retry in the Premiere UI.");
+          }
+          if (Math.abs(parseFloat(afterMoveStartTicks) - parseFloat(beforeMoveStartTicks)) > 1) {
+            return __error("The timeline changed: Premiere moved the clip to " + __ticksToSeconds(afterMoveStartTicks) + "s instead of keeping its start at " + __ticksToSeconds(beforeMoveStartTicks) + "s. Use Undo and retry in the Premiere UI.");
           }
           if (Math.abs((parseFloat(afterMoveEndTicks) - parseFloat(afterMoveStartTicks)) - spanTicks) > 1) {
-            return __error("Premiere changed the clip duration during the track move. Use Undo and retry in the Premiere UI.");
+            return __error("The timeline changed: Premiere changed the clip duration during the track move. Use Undo and retry in the Premiere UI.");
           }
-          if (String(after.clip.inPoint.ticks) !== beforeMoveInTicks || String(after.clip.outPoint.ticks) !== beforeMoveOutTicks) {
-            return __error("Premiere changed the clip's source in/out points during the track move. Use Undo and retry in the Premiere UI.");
+          var sourceReadable = true;
+          var afterInTicks = "";
+          var afterOutTicks = "";
+          try {
+            afterInTicks = String(after.clip.inPoint.ticks);
+            afterOutTicks = String(after.clip.outPoint.ticks);
+          } catch (eSourceRead) {
+            sourceReadable = false;
+          }
+          if (sourceReadable && (afterInTicks !== beforeMoveInTicks || afterOutTicks !== beforeMoveOutTicks)) {
+            return __error("The timeline changed: Premiere changed the clip's source in/out points during the track move. Use Undo and retry in the Premiere UI.");
           }
 
-          return __result({
+          var moveResult = {
             moved: true,
-            verified: true,
+            verified: sourceReadable,
+            outcome: sourceReadable ? "verified" : "committed_unverified",
             clipName: after.clip.name,
             newTrackIndex: after.trackIndex,
             startSeconds: __ticksToSeconds(afterMoveStartTicks),
             endSeconds: __ticksToSeconds(afterMoveEndTicks)
-          });
+          };
+          if (!sourceReadable) moveResult.warning = "The clip is on the destination track with the same start and duration, but its source in/out points could not be read back.";
+          return __result(moveResult);
         `);
                 return sendCommand(script, bridgeOptions);
             },

package/dist/tools/media.js

@@ -262,7 +262,7 @@ export function getMediaTools(bridgeOptions) {
             },
         },
         refresh_media: {
-            description: "Refresh a project item to pick up changes to the source file",
+            description: "Refresh a project item to pick up changes to the source file. The interpreted frame rate is read before and after; if the refresh leaves an implausible rate (seen on stills, e.g. 29.97 becoming 2.75e-8), the previous rate is restored and read back. Reports frameRateBefore, frameRateAfter and repaired.",
             parameters: {
                 type: "object",
                 properties: {
@@ -277,8 +277,33 @@ export function getMediaTools(bridgeOptions) {
                 const script = buildToolScript(`
           var item = __findProjectItem("${escapeForExtendScript(args.item_id)}");
           if (!item) return __error("Item not found: ${escapeForExtendScript(args.item_id)}");
+          // Some hosts corrupt the interpreted frame rate of stills on refresh
+          // (#642). Snapshot it, and restore it only when the new value is not a
+          // usable rate, so a real change in the source file is kept.
+          var readRate = function () {
+            try {
+              var interp = item.getFootageInterpretation();
+              var rate = interp ? Number(interp.frameRate) : NaN;
+              return isFinite(rate) ? rate : null;
+            } catch (eRate) { return null; }
+          };
+          var usableRate = function (rate) { return rate !== null && rate >= 1 && rate <= 1000; };
+          var before = readRate();
           item.refreshMedia();
-          return __result({ refreshed: true, item: item.name });
+          var after = readRate();
+          if (!usableRate(before) || usableRate(after)) {
+            return __result({ refreshed: true, item: item.name, frameRateBefore: before, frameRateAfter: after, repaired: false });
+          }
+          try {
+            var restore = item.getFootageInterpretation();
+            restore.frameRate = before;
+            item.setFootageInterpretation(restore);
+          } catch (eRestore) {}
+          var restored = readRate();
+          if (restored === null || Math.abs(restored - before) > 0.001) {
+            return __error("refresh_media refreshed " + item.name + ", but its frame rate changed from " + before + " to " + after + " and could not be restored (read back " + restored + "). Set it with set_footage_interpretation frame_rate " + before + ".");
+          }
+          return __result({ refreshed: true, item: item.name, frameRateBefore: before, frameRateAfter: restored, frameRateAfterRefresh: after, repaired: true });
         `);
                 return sendCommand(script, bridgeOptions);
             },

package/dist/tools/playback.js

@@ -35,7 +35,7 @@ export function getPlaybackTools(bridgeOptions) {
             },
         },
         play_source_monitor: {
-            description: "Request playback of the clip in the Source Monitor. The legacy API does not provide a same-call position readback, so movement is not reported as verified.",
+            description: "Request playback of the clip in the Source Monitor. Fails when no clip is loaded. The legacy API does not provide a same-call position readback, so movement is not reported as verified.",
             parameters: {
                 type: "object",
                 properties: {
@@ -47,12 +47,23 @@ export function getPlaybackTools(bridgeOptions) {
             },
             handler: async (args) => {
                 const speed = args.speed ?? 1.0;
+                if (typeof speed !== "number" || !Number.isFinite(speed) || speed === 0 || Math.abs(speed) > 64) {
+                    return { success: false, error: "speed must be a non-zero number from -64 to 64." };
+                }
                 const script = buildToolScript(`
+          // Premiere accepts play() with nothing loaded and does nothing (#642).
+          var loaded = null;
+          try {
+            if (typeof app.sourceMonitor.getProjectItem === "function") loaded = app.sourceMonitor.getProjectItem();
+            else loaded = undefined;
+          } catch (eLoaded) { loaded = undefined; }
+          if (loaded === null) return __error("No clip is loaded in the Source Monitor. Open one with open_in_source first.");
           app.sourceMonitor.play(${speed});
           return __result({
             playbackRequested: true,
             playbackVerified: false,
             speed: ${speed},
+            clip: loaded ? loaded.name : null,
             verificationScope: "Premiere accepted the source-monitor playback request only; poll get_source_monitor_position before treating movement as confirmed."
           });
         `);

package/dist/tools/project.d.ts

@@ -298,9 +298,14 @@ export declare function getProjectTools(bridgeOptions: BridgeOptions): {
                     type: string;
                     description: string;
                 };
+                bin_id: {
+                    type: string;
+                    description: string;
+                };
             };
         };
         handler: (args: {
+            bin_id?: string;
             width?: number;
             height?: number;
             timebase?: string;
@@ -354,8 +359,20 @@ export declare function getProjectTools(bridgeOptions: BridgeOptions): {
     };
     get_project_panel_metadata: {
         description: string;
-        parameters: {};
-        handler: () => Promise<import("../bridge/file-bridge.js").CommandResult>;
+        parameters: {
+            type: "object";
+            properties: {
+                max_chars: {
+                    type: string;
+                    minimum: number;
+                    maximum: number;
+                    description: string;
+                };
+            };
+        };
+        handler: (args?: {
+            max_chars?: number;
+        }) => Promise<import("../bridge/file-bridge.js").CommandResult>;
     };
     set_project_panel_metadata: {
         description: string;

package/dist/tools/project.js

@@ -1,5 +1,8 @@
 import { buildToolScript, escapeForExtendScript, } from "../bridge/script-builder.js";
 import { sendCommand } from "../bridge/file-bridge.js";
+const PROJECT_PANEL_METADATA_MIN_CHARS = 256;
+const PROJECT_PANEL_METADATA_MAX_CHARS = 200000;
+const PROJECT_PANEL_METADATA_DEFAULT_CHARS = 20000;
 export function getProjectTools(bridgeOptions) {
     return {
         save_project: {
@@ -596,6 +599,10 @@ export function getProjectTools(bridgeOptions) {
                         type: "string",
                         description: "Name for the bars and tone item (default: 'Bars and Tone')",
                     },
+                    bin_id: {
+                        type: "string",
+                        description: "Optional destination bin: node ID, slash-separated bin path from the project root, or bin name. The bin is resolved before anything is created; the item is moved there and its location read back.",
+                    },
                 },
             },
             handler: async (args) => {
@@ -615,6 +622,9 @@ export function getProjectTools(bridgeOptions) {
           var timebase = parseFloat(${args.timebase ? `"${escapeForExtendScript(args.timebase)}"` : `seq ? seq.timebase : "254016000000"`});
           if (!isFinite(timebase) || timebase <= 0) return __error("A positive sequence timebase is required to create bars and tone.");
           var requestedName = "${escapeForExtendScript(name)}";
+          var targetBin = null;
+          ${args.bin_id !== undefined ? `targetBin = __findBin("${escapeForExtendScript(String(args.bin_id))}");
+          if (!targetBin) return __error("Bin not found: ${escapeForExtendScript(String(args.bin_id))}. Nothing was created.");` : ""}
           // newBarsAndTone does not reliably return a ProjectItem with name and
           // nodeId (issue #588), so diff the project tree to find what it made.
           var beforeIds = __collectNodeIds(app.project.rootItem, {});
@@ -638,12 +648,22 @@ export function getProjectTools(bridgeOptions) {
           }
           var itemName = requestedName;
           try { itemName = item.name; } catch (eName) {}
+          var binPlacement = null;
+          if (targetBin) {
+            try { item.moveBin(targetBin); } catch (eMove) {}
+            var inBin = false;
+            try { inBin = String(item.treePath).indexOf(String(targetBin.treePath) + "\\\\") === 0; } catch (eInBin) {}
+            binPlacement = { bin: targetBin.name, moved: inBin };
+          }
           var treePath = null;
           try { treePath = item.treePath; } catch (eTreePath) {}
+          var placedOk = !binPlacement || binPlacement.moved;
           return __result({
             created: true,
-            verified: true,
-            outcome: "verified",
+            verified: placedOk,
+            outcome: placedOk ? "verified" : "committed_unverified",
+            bin: binPlacement,
+            note: placedOk ? null : "The item was created but could not be confirmed in the requested bin; move it with move_item_to_bin.",
             name: itemName,
             nodeId: __nodeIdOf(item),
             treePath: treePath,
@@ -766,13 +786,46 @@ export function getProjectTools(bridgeOptions) {
             },
         },
         get_project_panel_metadata: {
-            description: "Get the current Project-panel column layout as XML. This is schema/layout configuration, not per-item Scene/Shot/Take values; use inspect_project_panel_metadata_uxp item_columns or get_metadata for those.",
-            parameters: {},
-            handler: async () => {
+            description: "Get the current Project-panel column layout as XML. This is schema/layout configuration, not per-item Scene/Shot/Take values; use inspect_project_panel_metadata_uxp item_columns or get_metadata for those. Output is capped by max_chars (default 20000); when truncated is true the XML is incomplete and must not be passed to set_project_panel_metadata.",
+            parameters: {
+                type: "object",
+                properties: {
+                    max_chars: {
+                        type: "integer",
+                        minimum: PROJECT_PANEL_METADATA_MIN_CHARS,
+                        maximum: PROJECT_PANEL_METADATA_MAX_CHARS,
+                        description: `Maximum characters of metadata XML to return (${PROJECT_PANEL_METADATA_MIN_CHARS}-${PROJECT_PANEL_METADATA_MAX_CHARS}, default ${PROJECT_PANEL_METADATA_DEFAULT_CHARS}). Longer XML is cut at this length and reported with truncated: true and totalChars.`,
+                    },
+                },
+            },
+            handler: async (args = {}) => {
+                const maxChars = args?.max_chars ?? PROJECT_PANEL_METADATA_DEFAULT_CHARS;
+                if (typeof maxChars !== "number" ||
+                    !Number.isInteger(maxChars) ||
+                    maxChars < PROJECT_PANEL_METADATA_MIN_CHARS ||
+                    maxChars > PROJECT_PANEL_METADATA_MAX_CHARS) {
+                    return {
+                        success: false,
+                        error: `max_chars must be an integer between ${PROJECT_PANEL_METADATA_MIN_CHARS} and ${PROJECT_PANEL_METADATA_MAX_CHARS}`,
+                    };
+                }
                 const script = buildToolScript(`
           var meta = app.project.getProjectPanelMetadata();
           if (!meta) return __error("Could not retrieve project panel metadata");
-          return __result({ metadata: meta });
+          var text = String(meta);
+          var maxChars = ${maxChars};
+          var totalChars = text.length;
+          if (totalChars > maxChars) {
+            return __result({
+              metadata: text.substring(0, maxChars),
+              truncated: true,
+              totalChars: totalChars,
+              returnedChars: maxChars,
+              maxChars: maxChars,
+              note: "Metadata XML was truncated and is not well-formed. Raise max_chars (up to ${PROJECT_PANEL_METADATA_MAX_CHARS}) to read more; do not pass truncated XML to set_project_panel_metadata."
+            });
+          }
+          return __result({ metadata: text, truncated: false, totalChars: totalChars, returnedChars: totalChars, maxChars: maxChars });
         `);
                 return sendCommand(script, bridgeOptions);
             },