// GH #277: who watches a ticket (unique per ticket + analyst - db_verify_indexes.php).
    'ticket_watchers' => [
        'id'               => 'INT NOT NULL AUTO_INCREMENT',
        'ticket_id'        => 'INT NOT NULL',
        'analyst_id'       => 'INT NOT NULL',
        'added_by_id'      => 'INT NULL',
        'created_datetime' => 'DATETIME NOT NULL',
    ],

    ['ticket_watchers', 'uq_ticket_watchers', 'unique', '(`ticket_id`,`analyst_id`)'],
    ['ticket_watchers', 'ix_ticket_watchers_analyst', 'key', '(`analyst_id`)'],

/**
 * The rules:
 *   - Anyone who can SEE a ticket can watch it - read-only Tickets access too:
 *     following a ticket changes nothing on it.
 *   - Putting someone ELSE on it, or taking them off, needs write access to
 *     Tickets; anyone can always take themselves off.
 *   - Only an analyst who can see the ticket can be put on it, and the router
 *     checks again at every notification (a ticket moved to another company, an
 *     analyst whose access changed): a watcher who cannot see it hears nothing.
 *   - The assignee may watch too (to keep following a ticket after handing it on);
 *     nobody is ever notified twice about one event.
 *
 * A deactivated analyst is never told anything, whatever the setting. Tickets -> Settings ->
 * General -> "When a watcher is deactivated" decides what happens to their watches:
 *   - stop (the default): kept, but ignored - hidden from the ticket's watcher list and never
 *     notified - and back as they were if the analyst is made active again;
 *   - remove: deleted when the analyst is deactivated (analystDeactivated(), called from every
 *     place an analyst is switched off: analystDeactivate(), AnalystsService::update(),
 *     api/tickets/save_analyst.php). Anonymising always removes them (registry: personal).
 */

class TicketWatchers
{
    /** The ticket events a watcher can be told about - the ticket ones the owner gets, less "a new ticket" and "your team's queue". */
    public const EVENTS = [
        'ticket.reply_received', 'ticket.note_added', 'ticket.status_changed', 'ticket.priority_changed',
        'ticket.assigned', 'sla.warning', 'sla.breached',
    ];

    /** Is the table there yet (before Database Verify it is not)? Cached per request. */
    public static function ready(PDO $conn): bool
    {
        static $ok = null;
        if ($ok !== null) return $ok;
        try { $conn->query("SELECT 1 FROM ticket_watchers LIMIT 0"); return $ok = true; }
        catch (Throwable) { return $ok = false; }
    }

    /**
     * The events watchers are told about on this install (Tickets -> Settings -> General).
     * Never saved = all of them.
     */
    public static function events(PDO $conn): array
    {
        try {
            $s = $conn->prepare("SELECT setting_value FROM system_settings WHERE setting_key = 'ticket_watch_events'");
            $s->execute();
            $v = $s->fetchColumn();
        } catch (Throwable) {
            $v = false;
        }
        if ($v === false || $v === null) return self::EVENTS;
        return array_values(array_intersect(self::EVENTS, array_map('trim', explode(',', (string)$v))));
    }

    public static function list(PDO $conn, int $ticketId): array
    {
        if (!self::ready($conn)) return [];
        $st = $conn->prepare(
            "SELECT w.analyst_id, a.full_name AS name, w.added_by_id, b.full_name AS added_by_name, w.created_datetime
               FROM ticket_watchers w
               JOIN analysts a ON a.id = w.analyst_id
               LEFT JOIN analysts b ON b.id = w.added_by_id
              WHERE w.ticket_id = ? AND a.is_active = 1
              ORDER BY w.created_datetime ASC, w.id ASC");
        $st->execute([$ticketId]);
        return array_map(fn($r) => [
            'analyst_id'    => (int)$r['analyst_id'],
            'name'          => (string)$r['name'],
            'added_by'      => $r['added_by_id'] !== null ? (int)$r['added_by_id'] : null,
            'added_by_name' => $r['added_by_name'] !== null ? (string)$r['added_by_name'] : null,
            'added_at'      => (string)$r['created_datetime'],
        ], $st->fetchAll(PDO::FETCH_ASSOC));
    }

    public static function add(PDO $conn, ActorContext $ctx, int $ticketId, int $analystId, bool $canWrite): array
    {
        self::assertReady($conn);
        self::assertActorSees($conn, $ctx, $ticketId);
        if ($analystId !== $ctx->actorId && !$canWrite) {
            throw new ServiceError('forbidden', 'read_only', 'Adding a colleague needs write access to Tickets. You can still watch it yourself.');
        }
        $a = $conn->prepare("SELECT is_active FROM analysts WHERE id = ?");
        $a->execute([$analystId]);
        $active = $a->fetchColumn();
        if ($active === false || (int)$active !== 1) {
            throw new ServiceError('validation', 'invalid_field', 'That analyst does not exist or is inactive.');
        }
        if (!self::canSee($conn, $analystId, $ticketId)) {
            throw new ServiceError('validation', 'invalid_field', 'That analyst cannot see this ticket, so cannot watch it.');
        }
        $ex = $conn->prepare("SELECT 1 FROM ticket_watchers WHERE ticket_id = ? AND analyst_id = ?");
        $ex->execute([$ticketId, $analystId]);
        if ($ex->fetchColumn()) return ['added' => false];
        $conn->prepare("INSERT INTO ticket_watchers (ticket_id, analyst_id, added_by_id, created_datetime) VALUES (?, ?, ?, UTC_TIMESTAMP())")
             ->execute([$ticketId, $analystId, $ctx->actorId > 0 ? $ctx->actorId : null]);
        return ['added' => true];
    }

    public static function remove(PDO $conn, ActorContext $ctx, int $ticketId, int $analystId, bool $canWrite): array
    {
        self::assertReady($conn);
        self::assertActorSees($conn, $ctx, $ticketId);
        if ($analystId !== $ctx->actorId && !$canWrite) {
            throw new ServiceError('forbidden', 'read_only', 'Taking a colleague off needs write access to Tickets.');
        }
        $st = $conn->prepare("DELETE FROM ticket_watchers WHERE ticket_id = ? AND analyst_id = ?");
        $st->execute([$ticketId, $analystId]);
        return ['removed' => $st->rowCount() > 0];
    }

    /**
     * Can this analyst see this ticket - and does it exist?
     *
     * TRAP: analystCanAccessTicket() is a COMPANY check. On a single-company install
     * it is true for any id at all, so on its own it let a watch be stored against a
     * ticket that does not exist (found by tests/ticket-watchers.php).
     */
    public static function canSee(PDO $conn, int $analystId, int $ticketId): bool
    {
        if ($ticketId <= 0 || $analystId <= 0) return false;
        $s = $conn->prepare("SELECT 1 FROM tickets WHERE id = ?");
        $s->execute([$ticketId]);
        return (bool)$s->fetchColumn() && analystCanAccessTicket($conn, $analystId, $ticketId);
    }

    /** 404 for a ticket the actor cannot see - "not found", never "not yours". */
    private static function assertActorSees(PDO $conn, ActorContext $ctx, int $ticketId): void
    {
        if (!self::canSee($conn, $ctx->actorId, $ticketId)) {
            throw new ServiceError('not_found', 'not_found', 'Ticket not found.');
        }
    }

    /**
     * Who of a ticket's watchers should hear about this event: none unless watchers
     * are told about it here, and only those who are active and can still see the ticket.
     * For the notifications router. Never throws.
     *
     * @return list<int>
     */
    public static function audience(PDO $conn, string $event, int $ticketId): array
    {
        if ($ticketId <= 0 || !in_array($event, self::events($conn), true)) return [];
        try {
            $st = $conn->prepare("SELECT w.analyst_id FROM ticket_watchers w JOIN analysts a ON a.id = w.analyst_id WHERE w.ticket_id = ? AND a.is_active = 1");
            $st->execute([$ticketId]);
            $ids = array_map('intval', $st->fetchAll(PDO::FETCH_COLUMN));
        } catch (Throwable) {
            return [];   // before Database Verify: nobody watches yet
        }
        return array_values(array_filter($ids, fn($id) => analystCanAccessTicket($conn, $id, $ticketId)));
    }

    /**
     * What happens to a deactivated analyst's watches: 'stop' (kept, ignored, back on
     * reactivation) or 'remove'. Never saved = 'stop'.
     */
    public static function inactivePolicy(PDO $conn): string
    {
        try {
            $s = $conn->prepare("SELECT setting_value FROM system_settings WHERE setting_key = 'ticket_watch_inactive'");
            $s->execute();
            return $s->fetchColumn() === 'remove' ? 'remove' : 'stop';
        } catch (Throwable) {
            return 'stop';
        }
    }

    /**
     * An analyst has just been deactivated: with the 'remove' setting, take them off every
     * ticket they watch. With 'stop' nothing is deleted - list() and audience() skip inactive
     * analysts anyway. Never throws (it runs inside saving an analyst).
     *
     * @return int watches removed
     */
    public static function analystDeactivated(PDO $conn, int $analystId): int
    {
        if ($analystId <= 0 || !self::ready($conn) || self::inactivePolicy($conn) !== 'remove') return 0;
        try {
            $st = $conn->prepare("DELETE FROM ticket_watchers WHERE analyst_id = ?");
            $st->execute([$analystId]);
            return $st->rowCount();
        } catch (Throwable) {
            return 0;
        }
    }

    $one = notificationsRecipientFor($event, $payload);
    $ids = $one > 0 ? [$one] : [];

    // GH #277: the ticket's WATCHERS hear about it too, for the events Tickets ->
    // Settings -> General ticks - each through their own preferences (applied by
    // the caller, as for the assignee), and only while they can still see the
    // ticket. array_unique: an assignee who also watches is told once.
    if (in_array($event, TicketWatchers::EVENTS, true)) {
        $ticketId = (int)($payload['ticket']['id'] ?? $payload['ticket_id'] ?? 0);
        $ids = array_merge($ids, TicketWatchers::audience($conn, $event, $ticketId));
    }
    return array_values(array_unique(array_filter($ids)));

 * Tickets now have that deliberate list too: WATCHERS (GH #277, ticket_watchers),
 * put there by hand and removable - never "who has touched it", the firehose that
 * was rejected. They join the ticket events below that the install chose
 * (Tickets -> Settings -> General), and a reassignment reaches them as
 * 'ticket.reassigned', never as "assigned to you".

        // GH #277: "Assigned to you" is news for the new assignee alone. A watcher
        // told about the same reassignment gets its own type, worded "reassigned",
        // with its own switch in their preferences.
        $newAssignee = $event === 'ticket.assigned' ? notificationsRecipientFor($event, $payload) : 0;

        foreach ($recipients as $recipientId) {
            $type = ($event === 'ticket.assigned' && $recipientId !== $newAssignee) ? 'ticket.reassigned' : $event;
            // … (Rule 1: never tell people about their own action)
            if ($actorId > 0 && $actorId === $recipientId) {
                continue;
            }
            // Each person's OWN toggles decide. …
            if (!NotificationsService::typeEnabled($conn, $recipientId, $type)) {
                continue;
            }
            NotificationsService::notify($conn, [
                'analyst_id'  => $recipientId,
                'event_type'  => $type,
                // …
            ]);
        }

// includes/services/notifications.php - NotificationsService::types()
            'ticket.assigned'         => ['default' => true,  'entity' => 'ticket'],
            // GH #277: a ticket you WATCH moved to someone else. Not "assigned to you" -
            // that is news for the new assignee alone - and its own switch.
            'ticket.reassigned'       => ['default' => true,  'entity' => 'ticket'],

// lang/en/common.php - common.notifications
        'event' => [
            'ticket' => [
                'assigned'         => 'Assigned to you by {actor}',
                'reassigned'       => '{actor} reassigned it',   // GH #277: to a watcher
                // …
        'pref' => [
            'ticket' => [
                'assigned'         => 'A ticket is assigned to me',
                'reassigned'       => 'A ticket I watch is reassigned',
                'reply_received'   => 'A requester replies to my ticket, or one I watch',
                'note_added'       => 'Someone adds a note to my ticket, or one I watch',

            'setting_keys' => ['reopen_on_customer_reply', 'snooze_wake_hour', 'ticket_workspace_mode',
                                'ticket_watch_events',   // GH #277: what watchers are told about

                <!-- GH #277: what WATCHERS are told about. A tick per ticket event; all ticked
                     when never saved, and nobody watches anything until someone chooses to,
                     so an upgrade changes nothing. Each watcher's own notification settings
                     still apply on top. -->
                <h3 style="margin-top: 34px;"><?php echo htmlspecialchars(t('tickets.settings.general.watch_heading')); ?></h3>
                <div class="form-group" id="watchEventsGroup">
                    <?php foreach (TicketWatchers::EVENTS as $__ev): ?>
                    <label style="display:block;margin-top:6px;font-weight:400;">
                        <input type="checkbox" class="watch-event" value="<?php echo htmlspecialchars($__ev); ?>" checked>
                        <?php echo htmlspecialchars(t('tickets.settings.general.watch_event_' . str_replace('.', '_', $__ev))); ?>
                    </label>
                    <?php endforeach; ?>

                                'ticket_watch_events',   // GH #277: what watchers are told about
                                'ticket_watch_inactive', // ...and what happens to a deactivated analyst's watches

                <!-- A deactivated analyst is never told anything; this decides whether their
                     watches wait for them (stop, the default) or go (remove). TicketWatchers. -->
                <div class="form-group">
                    <label for="watchInactive"><?php echo htmlspecialchars(t('tickets.settings.general.watch_inactive_label')); ?></label>
                    <select id="watchInactive" style="max-width: 420px;">
                        <option value="stop"><?php echo htmlspecialchars(t('tickets.settings.general.watch_inactive_stop')); ?></option>
                        <option value="remove"><?php echo htmlspecialchars(t('tickets.settings.general.watch_inactive_remove')); ?></option>
                    </select>

// includes/ticket_merge.php
const MERGE_MOVE_DEDUPE = [
    'ticket_cmdb_objects' => 'cmdb_object_id',
    'ticket_assets'       => 'asset_id',
    'problem_tickets'     => 'problem_id',
    'change_tickets'      => 'change_id',
    'ticket_watchers'     => 'analyst_id',   // GH #277: watchers follow the conversation, once each
    'ticket_forms'        => 'form_id',      // GH #272: forms the work needs, once each (the survivor's own wins)
];

    foreach (MERGE_MOVE_DEDUPE as $table => $col) {
        try {
            // Note the ordering: the de-dupe DELETE runs first, so what is recorded
            // afterwards is exactly the set that actually moves. Recording before the
            // delete would promise an unmerge rows that no longer exist.
            $conn->prepare(
                "DELETE FROM `$table`
                  WHERE ticket_id = ?
                    AND `$col` IN (SELECT * FROM (SELECT `$col` FROM `$table` WHERE ticket_id = ?) x)"
            )->execute([$sourceId, $targetId]);

            $q = $conn->prepare("SELECT id FROM `$table` WHERE ticket_id = ?");
            $q->execute([$sourceId]);
            $rows = array_map('intval', $q->fetchAll(PDO::FETCH_COLUMN));
            if ($rows) $movedRelated[$table] = $rows;

            $conn->prepare("UPDATE `$table` SET ticket_id = ? WHERE ticket_id = ?")->execute([$targetId, $sourceId]);
        } catch (Exception) { /* absent */ }
    }

// api/tickets/permanently_delete_ticket.php
    // 6b. Watchers (GH #277) - no foreign key either. Tolerant: no table before Database Verify.
    try { $conn->prepare("DELETE FROM ticket_watchers WHERE ticket_id = ?")->execute([$ticketId]); } catch (PDOException $e) { if ((string)$e->getCode() !== '42S02') throw $e; }

// api/tickets/empty_trash.php
    // Checklists and watchers have no foreign key to cascade. Checklists were left behind here
    // (permanently_delete_ticket.php removed them; this did not); watchers are GH #277.
    // A table that is not there yet (42S02) is nothing to remove.
    foreach (["DELETE FROM ticket_checklist_items WHERE ticket_checklist_id IN (SELECT id FROM ticket_checklists WHERE ticket_id IN ($place))",
              "DELETE FROM ticket_checklists WHERE ticket_id IN ($place)",
              "DELETE FROM ticket_watchers WHERE ticket_id IN ($place)"] as $sql) {
        try { $conn->prepare($sql)->execute($ids); } catch (PDOException $e) { if ((string)$e->getCode() !== '42S02') throw $e; }
    }

// api/system/debug-tools/D002_delete_ticket.php
    ['ticket_watchers',     "DELETE FROM ticket_watchers WHERE ticket_id = ?", [$ticketId]],   // GH #277

// includes/analyst_lifecycle.php - analystReferenceRegistry()
        ['ticket_watchers', 'analyst_id', 'personal'],   // GH #277: anonymise removes them; deactivate follows the ticket_watch_inactive setting
        // …
        ['ticket_watchers', 'added_by_id', 'history'],

// includes/analyst_lifecycle.php - the leaving screen's Deactivate
function analystDeactivate(PDO $conn, ActorContext $ctx, int $analystId): void {
    analystLcAssertActionable($conn, $ctx, $analystId);
    $conn->prepare("UPDATE analysts SET is_active = 0, last_modified_datetime = UTC_TIMESTAMP() WHERE id = ?")->execute([$analystId]);
    require_once __DIR__ . '/services/ticket_watchers.php';
    TicketWatchers::analystDeactivated($conn, $analystId);   // the 'remove' setting: off every ticket they watched
    analystLcLog($conn, $ctx, $analystId, 'deactivated');
}

// includes/services/analysts.php - AnalystsService::update(): System → Analysts and the REST API
        if (array_key_exists('is_active', $in) && !self::flag($in['is_active'], 'is_active') && (int)$a['is_active'] === 1) {
            require_once __DIR__ . '/ticket_watchers.php';
            TicketWatchers::analystDeactivated($conn, $id);   // the 'remove' setting (Tickets -> Settings -> General)
        }

// api/tickets/save_analyst.php - the older analyst editor
        if (!$isActive) {
            // Deactivated (or saved while inactive): the 'remove' setting takes them off every
            // ticket they watch; 'stop' keeps the watches, ignored. Idempotent.
            require_once __DIR__ . '/../../includes/services/ticket_watchers.php';
            TicketWatchers::analystDeactivated($conn, $analystId);
        }