@@ -11,6 +11,10 @@ export type CommandSchema = {
   defaults?: Partial<CliFlags>;
   usageOverride?: string;
   listUsageOverride?: string;
+  // Swaps a shared flag's usageDescription for this command only, when the flag's generic
+  // documentation (flag-definitions-*.ts) does not fit every command it is allowed on — for
+  // example `--save-script` arms authoring on open/close but a repair transaction on replay.
+  flagDescriptionOverrides?: Partial<Record<FlagKey, string>>;
 };
 
 export type CommandSchemaOverride = Partial<CommandSchema>;
@@ -407,3 +407,35 @@ test('removed trigger aliases are no longer documented as commands', async () =>
   const help = await usageForCommand('trigger-screenshot-notification');
   assert.equal(help, null);
 });
+
+// #1558 follow-up: replay's --save-script arms an ADR 0012 repair transaction, not the
+// open/close authoring lifecycle (arm-on-open, publish-on-close) the shared flag describes.
+// `flagDescriptionOverrides` (CommandSchema) swaps the text for replay only; open/close keep the
+// shared FlagDefinition description unchanged.
+test('replay --save-script help describes arming a repair transaction, not open/close authoring', async () => {
+  const help = await usageForCommand('replay');
+  if (help === null) throw new Error('Expected replay help text');
+  assert.match(help, /Arm a repair transaction from this replay \(ADR 0012\)/);
+  assert.match(help, /commits when the repair-armed session tears down/);
+  assert.doesNotMatch(help, /Arm evidence capture on open, publish the armed recording on close/);
+});
+
+test('open --save-script help keeps the shared open\\/close authoring description', async () => {
+  const help = await usageForCommand('open');
+  if (help === null) throw new Error('Expected open help text');
+  assert.match(
+    help,
+    /Arm evidence capture on open, publish the armed recording on close; close --save-script alone \(without an armed open\) is rejected/,
+  );
+  assert.doesNotMatch(help, /Arm a repair transaction from this replay/);
+});
+
+test('close --save-script help keeps the shared open\\/close authoring description', async () => {
+  const help = await usageForCommand('close');
+  if (help === null) throw new Error('Expected close help text');
+  assert.match(
+    help,
+    /Arm evidence capture on open, publish the armed recording on close; close --save-script alone \(without an armed open\) is rejected/,
+  );
+  assert.doesNotMatch(help, /Arm a repair transaction from this replay/);
+});
@@ -1243,6 +1243,21 @@ function listHelpFlags(keys: ReadonlySet<FlagKey>): FlagDefinition[] {
   );
 }
 
+// Command-specific override for a shared flag's help text (see CommandSchema.flagDescriptionOverrides):
+// keeps the FlagDefinition registry as one shared row per flag while letting a command whose
+// semantics genuinely differ (e.g. `replay --save-script` arms a repair transaction, not the
+// open/close authoring lifecycle) show its own description without duplicating the flag entry.
+function applyFlagDescriptionOverrides(
+  definitions: FlagDefinition[],
+  overrides: Partial<Record<FlagKey, string>> | undefined,
+): FlagDefinition[] {
+  if (!overrides) return definitions;
+  return definitions.map((definition) => {
+    const override = overrides[definition.key];
+    return override === undefined ? definition : { ...definition, usageDescription: override };
+  });
+}
+
 function renderFlagSection(title: string, definitions: FlagDefinition[]): string {
   return renderAlignedSection(
     title,
@@ -1302,7 +1317,10 @@ export function buildCommandUsageText(commandName: string): string | null {
   const schema = getCommandSchema(commandName);
   if (!schema) return null;
   const usage = buildCommandUsage(commandName, schema);
-  const commandFlags = listHelpFlags(new Set<FlagKey>(schema.allowedFlags ?? []));
+  const commandFlags = applyFlagDescriptionOverrides(
+    listHelpFlags(new Set<FlagKey>(schema.allowedFlags ?? [])),
+    schema.flagDescriptionOverrides,
+  );
   const sections: string[] = [];
   if (commandFlags.length > 0) {
     sections.push(renderFlagSection('Command flags:', commandFlags));
 
@@ -280,22 +280,26 @@ function describeCliSurface(command: string, schema: CommandSchema): CommandExpl
   return {
     usage: buildCommandUsage(command, schema),
     positionalArgs: schema.positionalArgs ?? [],
-    commandFlags: describeFlags(schema.allowedFlags ?? []),
-    supportedFlags: describeFlags(schema.supportedFlags ?? []),
+    commandFlags: describeFlags(schema.allowedFlags ?? [], schema.flagDescriptionOverrides),
+    supportedFlags: describeFlags(schema.supportedFlags ?? [], schema.flagDescriptionOverrides),
     globalFlags: describeFlags([...GLOBAL_FLAG_KEYS]),
   };
 }
 
-function describeFlags(keys: readonly FlagKey[]): CommandFlagExplanation[] {
+function describeFlags(
+  keys: readonly FlagKey[],
+  overrides?: Partial<Record<FlagKey, string>>,
+): CommandFlagExplanation[] {
   return [...new Set(keys)].sort().map((key) => {
     const definitions = flagDefinitionsByKey.get(key) ?? [];
     const preferred = definitions.find((definition) => definition.usageLabel) ?? definitions[0];
+    const description = overrides?.[key] ?? preferred?.usageDescription;
     return {
       key,
       syntax:
         preferred?.usageLabel ??
         [...new Set(definitions.flatMap((definition) => definition.names))].join('/'),
-      ...(preferred?.usageDescription ? { description: preferred.usageDescription } : {}),
+      ...(description ? { description } : {}),
     };
   });
 }
 
@@ -112,6 +112,13 @@ const replayCliSchema = {
     'saveScript',
     'force',
   ],
+  // ADR 0012 decision 6: on replay, --save-script arms a repair transaction from step 1 (not the
+  // open/close authoring lifecycle the shared flag description documents) and the healed script
+  // commits on that transaction's own teardown, not on a plain close.
+  flagDescriptionOverrides: {
+    saveScript:
+      'Arm a repair transaction from this replay (ADR 0012): recording starts at step 1, and the healed script commits when the repair-armed session tears down (close, close --save-script, or idle-reap). Independent of the open/close authoring arm-on-open. Optional custom output path.',
+  },
 } as const satisfies CommandSchemaOverride;
 
 const testCliSchema = {
 
@@ -1097,7 +1097,11 @@ test('targeted close skips platform dispatch and preserves the error when the re
     reason: 'runner_stop_failed',
     hint: 'Retry once the runner is reachable.',
   });
-  mockStopIosRunnerSession.mockRejectedValue(preCloseError);
+  // Scoped to this test's own two internal calls (pre-close stop, then the later
+  // independent-cleanup retry) — a persistent `mockRejectedValue` here would leak into every
+  // later test that exercises an Apple-platform runner stop, since `vi.clearAllMocks()` in
+  // `beforeEach` clears call history but not a mock's implementation.
+  mockStopIosRunnerSession.mockRejectedValueOnce(preCloseError);
 
   await expect(
     handleSessionCommands({
@@ -1140,18 +1144,16 @@ test('targeted close skips platform dispatch and preserves the error when the re
 // can retry, and no script file is written.
 test('close --save-script on a never-armed session is rejected before teardown, with no script written', async () => {
   const sessionStore = makeSessionStore();
-  const sessionName = 'android-unarmed-close-save-script-session';
+  const sessionName = 'ios-unarmed-close-save-script-session';
   const scriptPath = path.join(os.tmpdir(), `agent-device-unarmed-close-${Date.now()}.ad`);
-  sessionStore.set(
-    sessionName,
-    makeSession(sessionName, {
-      platform: 'android',
-      id: 'emulator-5554',
-      name: 'Pixel_9_API_35',
-      kind: 'emulator',
-      booted: true,
-    }),
-  );
+  // The fixture must carry real cleanup-bearing state (here: an active recording, like
+  // `makeIosSimulatorRecordingSession`'s other consumers) so this test can actually prove the
+  // guard runs *before* `stopBestEffortSessionResources` — not just that the response rejects.
+  // Without it, moving the guard after teardown would still pass: there would be nothing for
+  // teardown to observably touch.
+  const session = makeIosSimulatorRecordingSession(sessionName);
+  const kill = recordingKillMock(session);
+  sessionStore.set(sessionName, session);
 
   await expect(
     handleSessionCommands({
@@ -1178,8 +1180,15 @@ test('close --save-script on a never-armed session is rejected before teardown,
   // The rejection does not tear down the session — it stays retryable/recoverable.
   expect(sessionStore.get(sessionName)).toBeDefined();
   expect(fs.existsSync(scriptPath)).toBe(false);
-
-  // A plain close (no --save-script) still closes the same session cleanly afterward.
+  // No teardown hook ran: the recording is still live (recorder never signaled) and the runner
+  // was never told to stop. This is the assertion that goes red if the guard moves after
+  // `stopBestEffortSessionResources` — see the counterfactual in the PR description.
+  expect(kill).not.toHaveBeenCalled();
+  expect(session.recording).toBeDefined();
+  expect(mockStopIosRunnerSession).not.toHaveBeenCalled();
+
+  // A plain close (no --save-script) still closes the same session cleanly afterward, and now
+  // teardown genuinely does run: the recorder is signaled and the session deleted.
   const plainClose = await handleSessionCommands({
     req: {
       token: 't',
@@ -1194,6 +1203,9 @@ test('close --save-script on a never-armed session is rejected before teardown,
     invoke: noopInvoke,
   });
   expect(plainClose?.ok).toBe(true);
+  expect(kill).toHaveBeenCalledWith('SIGINT');
+  expect(session.recording).toBeUndefined();
+  expect(mockStopIosRunnerSession).toHaveBeenCalledWith(session.device.id);
   expect(sessionStore.get(sessionName)).toBeUndefined();
 });
 
 
@@ -148,7 +148,9 @@ grep -rnE "\\bgesture[[:space:]]+rotate([[:space:]]+$num){4}" --include='*.ad' .
 ```
 
 Re-recording also produces a migrated script: the recorder writes the canonical form, so a fresh
-`open` → interact → `close --save-script` run is a valid alternative to editing by hand.
+`open --save-script` → interact → `close` run is a valid alternative to editing by hand. Recording
+evidence is only captured from action zero, so arm at `open`; a bare `close --save-script` on a
+session that was not armed at `open` is rejected.
 
 ### Maestro flows