Merge branch 'main' into feature/best-general-hall-of-fame-parity

# Conflicts:
#	docs/frontend-legacy-parity.md

tools/frontend-legacy-parity/inheritance-management.spec.ts

@@ -0,0 +1,238 @@
+import { expect, test, type Page, type Route } from '@playwright/test';
+import { readFile } from 'node:fs/promises';
+import { dirname, extname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const repositoryRoot = resolve(dirname(fileURLToPath(import.meta.url)), '../..');
+const imageRoot = resolve(repositoryRoot, '../../image');
+const artifactRoot = process.env.FRONTEND_PARITY_ARTIFACT_DIR;
+const gameUrl = `http://127.0.0.1:${process.env.FRONTEND_PARITY_GAME_PORT ?? '15102'}/che/inherit`;
+
+const response = (data: unknown) => ({ result: { data } });
+
+const operations = (route: Route): string[] => {
+    const pathname = new URL(route.request().url()).pathname;
+    return decodeURIComponent(pathname.slice(pathname.lastIndexOf('/trpc/') + 6)).split(',');
+};
+
+const installImages = async (page: Page): Promise<void> => {
+    await page.route('**/image/**', async (route) => {
+        const relative = decodeURIComponent(new URL(route.request().url()).pathname).replace(/^\/image\//, '');
+        for (const candidate of [
+            resolve(imageRoot, relative),
+            resolve(imageRoot, 'game', relative),
+            resolve(imageRoot, 'icons', '22.jpg'),
+        ]) {
+            try {
+                const body = await readFile(candidate);
+                await route.fulfill({
+                    status: 200,
+                    contentType: extname(candidate).toLowerCase() === '.png' ? 'image/png' : 'image/jpeg',
+                    body,
+                });
+                return;
+            } catch {
+                // 다음 공개 image root 후보를 확인한다.
+            }
+        }
+        await route.abort('failed');
+    });
+};
+
+const statusFixture = {
+    items: {
+        previous: 12_000,
+        lived_month: 240,
+        max_domestic_critical: 80,
+        active_action: 35,
+        combat: 150,
+        sabotage: 60,
+        dex: 42,
+        unifier: 0,
+        tournament: 30,
+        betting: 20,
+        max_belong: 8,
+    },
+    totalPoint: 12_665,
+    inheritConst: {
+        minMonthToAllowInheritItem: 4,
+        inheritBornSpecialPoint: 6000,
+        inheritBornTurntimePoint: 2500,
+        inheritBornCityPoint: 1000,
+        inheritBornStatPoint: 1000,
+        inheritItemUniqueMinPoint: 5000,
+        inheritItemRandomPoint: 3000,
+        inheritBuffPoints: [0, 200, 600, 1200, 2000, 3000],
+        inheritSpecificSpecialPoint: 4000,
+        inheritResetAttrPointBase: [1000, 1000, 2000, 3000],
+        inheritCheckOwnerPoint: 1000,
+    },
+    buffLevels: {
+        warAvoidRatio: 0,
+        warCriticalRatio: 1,
+        warMagicTrialProb: 0,
+        domesticSuccessProb: 0,
+        domesticFailProb: 0,
+        warAvoidRatioOppose: 0,
+        warCriticalRatioOppose: 0,
+        warMagicTrialProbOppose: 0,
+    },
+    resetCosts: { resetSpecialWar: 1000, resetTurnTime: 1000 },
+    resetLevels: { resetSpecialWar: 0, resetTurnTime: 0 },
+    availableSpecialWar: [{ key: 'che_선봉', name: '선봉', info: '공격에 유리합니다.' }],
+    availableUnique: [
+        {
+            key: 'che_무기_12_칠성검',
+            name: '칠성검(+12)',
+            rawName: '칠성검',
+            info: '무력을 올려주는 유니크 무기입니다.',
+        },
+    ],
+    availableTargetGenerals: [{ id: 8, name: '조조' }],
+    turnTimeZones: ['00:00'],
+    isUnited: false,
+    currentSpecialWar: 'che_선봉',
+    currentStat: { leadership: 70, strength: 45, intel: 85 },
+};
+
+const installFixture = async (page: Page, options: { failBuff?: boolean } = {}) => {
+    let buffMutationCount = 0;
+    await installImages(page);
+    await page.addInitScript(() => {
+        window.localStorage.setItem('sammo-game-token', 'ga_inherit-visual-token');
+        window.localStorage.setItem('sammo-game-profile', 'che');
+    });
+    await page.route('**/che/api/trpc/**', async (route) => {
+        const names = operations(route);
+        if (options.failBuff && names.includes('inherit.buyHiddenBuff')) {
+            await route.fulfill({
+                status: 500,
+                contentType: 'application/json',
+                body: JSON.stringify({ error: { message: '의도한 유산 구입 오류' } }),
+            });
+            return;
+        }
+        const result = names.map((name) => {
+            if (name === 'inherit.getStatus') return response(statusFixture);
+            if (name === 'lobby.info') {
+                return response({
+                    profile: { id: 'che', scenario: 'default', name: '체섭' },
+                    world: { year: 200, month: 4 },
+                    myGeneral: { id: 7, name: '유비', nationId: 1 },
+                });
+            }
+            if (name === 'inherit.getLogs') {
+                return response([
+                    {
+                        id: 2,
+                        year: 200,
+                        month: 4,
+                        text: '1000 포인트로 장수 소유자 확인',
+                        createdAt: '2026-07-26T00:00:00.000Z',
+                    },
+                ]);
+            }
+            if (name === 'join.getConfig') {
+                return response({ rules: { stat: { total: 200, min: 10, max: 100 } } });
+            }
+            if (name === 'inherit.buyHiddenBuff') {
+                buffMutationCount += 1;
+                return response({ ok: true, remainPoint: 11_800 });
+            }
+            throw new Error(`Unhandled inheritance fixture operation: ${name}`);
+        });
+        await route.fulfill({
+            status: 200,
+            contentType: 'application/json',
+            body: JSON.stringify(result),
+        });
+    });
+    return { buffMutationCount: () => buffMutationCount };
+};
+
+test.describe('inheritance management legacy parity', () => {
+    test('matches the ref 1000px grid and computed styles on desktop and mobile', async ({ page }) => {
+        await installFixture(page);
+        await page.setViewportSize({ width: 1280, height: 900 });
+        await page.goto(gameUrl);
+        await expect(page.locator('#container')).toBeVisible();
+        await expect(page.locator('#specific-unique')).toHaveValue('che_무기_12_칠성검');
+
+        const desktop = await page.evaluate(() => {
+            const rect = (selector: string) => {
+                const box = document.querySelector<HTMLElement>(selector)!.getBoundingClientRect();
+                return { x: box.x, width: box.width };
+            };
+            const container = getComputedStyle(document.querySelector<HTMLElement>('#container')!);
+            const title = getComputedStyle(document.querySelector<HTMLElement>('.section-title')!);
+            const button = getComputedStyle(document.querySelector<HTMLElement>('.buy-button')!);
+            return {
+                container: rect('#container'),
+                firstPoint: rect('#inherit_sum'),
+                fontFamily: container.fontFamily,
+                fontSize: container.fontSize,
+                backgroundImage: container.backgroundImage,
+                titleBackgroundImage: title.backgroundImage,
+                buttonBackground: button.backgroundColor,
+            };
+        });
+
+        expect(desktop.container.width).toBe(1000);
+        expect(desktop.container.x).toBe(140);
+        expect(desktop.firstPoint.width).toBeCloseTo(327.3, 0);
+        expect(desktop.fontFamily).toContain('Pretendard');
+        expect(desktop.fontSize).toBe('14px');
+        expect(desktop.backgroundImage).toContain('back_walnut.jpg');
+        expect(desktop.titleBackgroundImage).toContain('back_green.jpg');
+
+        const buyButton = page.locator('.buy-button').first();
+        const beforeHover = await buyButton.evaluate((element) => getComputedStyle(element).backgroundColor);
+        await buyButton.hover();
+        const afterHover = await buyButton.evaluate((element) => getComputedStyle(element).backgroundColor);
+        expect(afterHover).not.toBe(beforeHover);
+        await buyButton.focus();
+        await expect(buyButton).toBeFocused();
+
+        if (artifactRoot) {
+            await page.screenshot({ path: resolve(artifactRoot, 'inherit-core-desktop.png'), fullPage: true });
+        }
+
+        await page.setViewportSize({ width: 500, height: 900 });
+        await page.reload();
+        await expect(page.locator('#container')).toBeVisible();
+        const mobile = await page.evaluate(() => {
+            const container = document.querySelector<HTMLElement>('#container')!.getBoundingClientRect();
+            const first = document.querySelector<HTMLElement>('#inherit_sum')!.getBoundingClientRect();
+            const second = document.querySelector<HTMLElement>('#inherit_previous')!.getBoundingClientRect();
+            return {
+                containerWidth: container.width,
+                firstWidth: first.width,
+                stacked: second.y > first.y,
+            };
+        });
+        expect(mobile.containerWidth).toBe(500);
+        expect(mobile.firstWidth).toBeCloseTo(482, 0);
+        expect(mobile.stacked).toBe(true);
+    });
+
+    test('submits a legacy buff purchase and refreshes status and logs', async ({ page }) => {
+        const fixture = await installFixture(page);
+        page.on('dialog', (dialog) => dialog.accept());
+        await page.goto(gameUrl);
+        await page.locator('#buff-warAvoidRatio').fill('1');
+        await page.locator('#buff-warAvoidRatio').locator('xpath=../..').getByRole('button', { name: '구입' }).click();
+        await expect.poll(fixture.buffMutationCount).toBe(1);
+        await expect(page.locator('#inherit_previous_value')).toHaveValue('12,000');
+    });
+
+    test('keeps controls usable and renders an API mutation error', async ({ page }) => {
+        await installFixture(page, { failBuff: true });
+        page.on('dialog', (dialog) => dialog.accept());
+        await page.goto(gameUrl);
+        await page.locator('#buff-warAvoidRatio').fill('1');
+        await page.locator('#buff-warAvoidRatio').locator('xpath=../..').getByRole('button', { name: '구입' }).click();
+        await expect(page.locator('[role="alert"]')).toBeVisible();
+        await expect(page.locator('#buff-warAvoidRatio')).toHaveValue('1');
+        await expect(page.locator('#buff-warAvoidRatio')).toBeEnabled();
+    });
+});

tools/frontend-legacy-parity/playwright.config.mjs

@@ -13,6 +13,7 @@ export default defineConfig({
         'public-gaps.spec.ts',
         'instant-diplomacy-message.spec.ts',
         'tournament-betting.spec.ts',
+        'inheritance-management.spec.ts',
     ],
     fullyParallel: false,
     workers: 1,

tools/frontend-legacy-parity/reference-current-city.mjs

@@ -0,0 +1,128 @@
+import { chromium } from '@playwright/test';
+import { createHash } from 'node:crypto';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+
+const baseUrl = process.env.REF_PARITY_URL ?? 'http://127.0.0.1:3400/sam/';
+const username = process.env.REF_PARITY_USER ?? 'refadmin';
+const passwordFile = process.env.REF_PARITY_PASSWORD_FILE;
+const artifactRoot = resolve(process.env.REF_PARITY_ARTIFACT_DIR ?? 'test-results/reference-current-city');
+
+if (!passwordFile) {
+    throw new Error('REF_PARITY_PASSWORD_FILE is required.');
+}
+
+const password = (await readFile(passwordFile, 'utf8')).trim();
+await mkdir(artifactRoot, { recursive: true });
+
+const browser = await chromium.launch({ headless: true });
+try {
+    const context = await browser.newContext({
+        viewport: { width: 1200, height: 900 },
+        deviceScaleFactor: 1,
+        locale: 'ko-KR',
+        timezoneId: 'Asia/Seoul',
+        colorScheme: 'dark',
+    });
+    const page = await context.newPage();
+    await page.goto(baseUrl, { waitUntil: 'networkidle' });
+    const globalSalt = await page.locator('#global_salt').inputValue();
+    const passwordHash = createHash('sha512')
+        .update(globalSalt + password + globalSalt)
+        .digest('hex');
+    const loginResponse = await context.request.post(new URL('api.php?path=Login/LoginByID', baseUrl).toString(), {
+        data: { username, password: passwordHash },
+    });
+    const loginResult = await loginResponse.json();
+    if (!loginResponse.ok() || loginResult.result !== true) {
+        throw new Error('Reference login failed.');
+    }
+
+    await page.goto(new URL('hwe/', baseUrl).toString(), { waitUntil: 'networkidle' });
+    const mapCity = page.locator('a[href*="b_currentCity.php?citylist="]').first();
+    const hasMapCity = await mapCity.isVisible({ timeout: 8_000 }).catch(() => false);
+    let mapInteraction;
+    if (hasMapCity) {
+        mapInteraction = await mapCity.evaluate((element) => ({
+            available: true,
+            href: element.getAttribute('href'),
+            cursor: getComputedStyle(element).cursor,
+            rect: (() => {
+                const box = element.getBoundingClientRect();
+                return { x: box.x, y: box.y, width: box.width, height: box.height };
+            })(),
+        }));
+        await mapCity.click();
+        await page.waitForLoadState('networkidle');
+        if (!page.url().includes('b_currentCity.php?citylist=')) {
+            throw new Error(`Reference map click did not open current city: ${page.url()}`);
+        }
+    } else {
+        mapInteraction = {
+            available: false,
+            pageUrl: page.url(),
+            pageTitle: await page.title(),
+        };
+        await page.goto(new URL('hwe/b_currentCity.php', baseUrl).toString(), { waitUntil: 'networkidle' });
+    }
+
+    const measurements = await page.evaluate(() => {
+        const measure = (element) => {
+            const box = element.getBoundingClientRect();
+            const style = getComputedStyle(element);
+            return {
+                rect: { x: box.x, y: box.y, width: box.width, height: box.height },
+                style: {
+                    fontFamily: style.fontFamily,
+                    fontSize: style.fontSize,
+                    lineHeight: style.lineHeight,
+                    color: style.color,
+                    backgroundColor: style.backgroundColor,
+                    backgroundImage: style.backgroundImage,
+                    borderCollapse: style.borderCollapse,
+                    padding: style.padding,
+                    textAlign: style.textAlign,
+                },
+            };
+        };
+        const tables = [...document.querySelectorAll('table')];
+        const selector = document.querySelector('#citySelector');
+        const stats = tables.find((table) => table.textContent?.includes('90병장'));
+        const generals = document.querySelector('#general_list')?.closest('table');
+        const firstIcon = document.querySelector('.generalIcon');
+        const title = stats?.querySelector('tr:first-child td');
+        return {
+            body: measure(document.body),
+            tables: tables.map(measure),
+            selector: selector ? measure(selector) : null,
+            stats: stats ? measure(stats) : null,
+            generals: generals ? measure(generals) : null,
+            firstIcon: firstIcon
+                ? {
+                      ...measure(firstIcon),
+                      naturalWidth: firstIcon.naturalWidth,
+                      naturalHeight: firstIcon.naturalHeight,
+                  }
+                : null,
+            title: title ? measure(title) : null,
+            document: {
+                width: document.documentElement.scrollWidth,
+                height: document.documentElement.scrollHeight,
+            },
+        };
+    });
+
+    await page.screenshot({
+        path: resolve(artifactRoot, 'reference-current-city-desktop.png'),
+        fullPage: true,
+        animations: 'disabled',
+    });
+    await writeFile(
+        resolve(artifactRoot, 'reference-current-city-computed-dom.json'),
+        `${JSON.stringify({ mapInteraction, currentCity: measurements }, null, 2)}\n`
+    );
+    process.stdout.write(`${JSON.stringify({ ok: true, artifactRoot })}\n`);
+    await context.close();
+} finally {
+    await browser.close();
+}

tools/frontend-legacy-parity/reference-general-lists.mjs

@@ -0,0 +1,91 @@
+import { chromium } from '@playwright/test';
+import { createHash } from 'node:crypto';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+
+const baseUrl = process.env.REF_GENERAL_URL ?? 'http://127.0.0.1:3400/sam/';
+const username = process.env.REF_GENERAL_USER ?? 'refuser1';
+const passwordFile = process.env.REF_GENERAL_PASSWORD_FILE;
+const artifactRoot = resolve(process.env.REF_GENERAL_ARTIFACT_DIR ?? 'test-results/reference-general-lists');
+if (!passwordFile) throw new Error('REF_GENERAL_PASSWORD_FILE is required.');
+const password = (await readFile(passwordFile, 'utf8')).trim();
+await mkdir(artifactRoot, { recursive: true });
+
+const measure = async (page, selectors) =>
+    page.evaluate((items) => {
+        const result = {};
+        for (const [name, selector] of Object.entries(items)) {
+            const element = document.querySelector(selector);
+            if (!element) {
+                result[name] = null;
+                continue;
+            }
+            const rect = element.getBoundingClientRect();
+            const style = getComputedStyle(element);
+            result[name] = {
+                rect: { x: rect.x, y: rect.y, width: rect.width, height: rect.height },
+                style: {
+                    fontFamily: style.fontFamily,
+                    fontSize: style.fontSize,
+                    borderCollapse: style.borderCollapse,
+                    backgroundImage: style.backgroundImage,
+                    color: style.color,
+                },
+            };
+        }
+        return { elements: result, documentWidth: document.documentElement.scrollWidth };
+    }, selectors);
+
+const browser = await chromium.launch({ headless: true });
+try {
+    const context = await browser.newContext({
+        viewport: { width: 1200, height: 900 },
+        deviceScaleFactor: 1,
+        locale: 'ko-KR',
+        colorScheme: 'dark',
+    });
+    const page = await context.newPage();
+    await page.goto(baseUrl, { waitUntil: 'networkidle' });
+    const salt = await page.locator('#global_salt').inputValue();
+    const passwordHash = createHash('sha512')
+        .update(salt + password + salt)
+        .digest('hex');
+    const login = await context.request.post(new URL('api.php?path=Login/LoginByID', baseUrl).toString(), {
+        data: { username, password: passwordHash },
+    });
+    const loginResult = await login.json();
+    if (!login.ok() || loginResult.result !== true) throw new Error('Reference login failed.');
+
+    const output = {};
+    for (const [name, path, selectors] of [
+        [
+            'generals',
+            'hwe/b_myGenInfo.php',
+            {
+                body: 'body',
+                title: 'body > table:first-of-type',
+                list: 'body > table:nth-of-type(2)',
+                firstRow: 'body > table:nth-of-type(2) tr:nth-child(2)',
+            },
+        ],
+        [
+            'secret',
+            'hwe/b_genList.php',
+            {
+                body: 'body',
+                title: 'body > table:first-of-type',
+                summary: 'body > table:nth-of-type(2)',
+                list: '#general_list',
+                firstRow: '#general_list tbody tr:first-child',
+            },
+        ],
+    ]) {
+        await page.goto(new URL(path, baseUrl).toString(), { waitUntil: 'networkidle' });
+        output[name] = await measure(page, selectors);
+        await page.screenshot({ path: resolve(artifactRoot, `ref-${name}.png`), fullPage: true });
+    }
+    await writeFile(resolve(artifactRoot, 'computed-dom.json'), `${JSON.stringify(output, null, 2)}\n`);
+    process.stdout.write(`${JSON.stringify({ ok: true, artifactRoot, output })}\n`);
+} finally {
+    await browser.close();
+}

tools/frontend-legacy-parity/reference-npc-policy.mjs

@@ -0,0 +1,117 @@
+import { chromium } from '@playwright/test';
+import { createHash } from 'node:crypto';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+
+const baseUrl = process.env.REF_PARITY_URL ?? 'http://127.0.0.1:3400/sam/';
+const username = process.env.REF_PARITY_USER ?? 'refadmin';
+const passwordFile = process.env.REF_PARITY_PASSWORD_FILE;
+const artifactRoot = resolve(process.env.REF_PARITY_ARTIFACT_DIR ?? 'test-results/reference-npc-policy');
+
+if (!passwordFile) {
+    throw new Error('REF_PARITY_PASSWORD_FILE is required.');
+}
+
+const password = (await readFile(passwordFile, 'utf8')).trim();
+await mkdir(artifactRoot, { recursive: true });
+
+const login = async (context, page) => {
+    await page.goto(baseUrl, { waitUntil: 'networkidle' });
+    const globalSalt = await page.locator('#global_salt').inputValue();
+    const passwordHash = createHash('sha512')
+        .update(globalSalt + password + globalSalt)
+        .digest('hex');
+    const response = await context.request.post(new URL('api.php?path=Login/LoginByID', baseUrl).toString(), {
+        data: { username, password: passwordHash },
+    });
+    const result = await response.json();
+    if (!response.ok() || result.result !== true) {
+        throw new Error('Reference login failed.');
+    }
+};
+
+const browser = await chromium.launch({ headless: true });
+try {
+    const result = {};
+    for (const viewport of [
+        { name: 'desktop', width: 1000, height: 900 },
+        { name: 'mobile', width: 500, height: 900 },
+    ]) {
+        const context = await browser.newContext({
+            viewport: { width: viewport.width, height: viewport.height },
+            deviceScaleFactor: 1,
+            locale: 'ko-KR',
+            timezoneId: 'Asia/Seoul',
+            colorScheme: 'dark',
+        });
+        const page = await context.newPage();
+        await login(context, page);
+        await page.goto(new URL('hwe/', baseUrl).toString(), { waitUntil: 'networkidle' });
+        await page.goto(new URL('hwe/v_NPCControl.php', baseUrl).toString(), { waitUntil: 'networkidle' });
+        try {
+            await page.locator('#container').waitFor({ timeout: 10_000 });
+        } catch {
+            throw new Error(
+                `Reference NPC policy failed to mount: ${JSON.stringify({
+                    url: page.url(),
+                    text: (await page.locator('body').innerText()).slice(0, 500),
+                })}`
+            );
+        }
+        result[viewport.name] = await page.evaluate(() => {
+            const measure = (selector) => {
+                const element = document.querySelector(selector);
+                if (!element) return null;
+                const rect = element.getBoundingClientRect();
+                const style = getComputedStyle(element);
+                return {
+                    rect: { x: rect.x, y: rect.y, width: rect.width, height: rect.height },
+                    style: {
+                        display: style.display,
+                        gridTemplateColumns: style.gridTemplateColumns,
+                        fontFamily: style.fontFamily,
+                        fontSize: style.fontSize,
+                        lineHeight: style.lineHeight,
+                        color: style.color,
+                        backgroundColor: style.backgroundColor,
+                        backgroundImage: style.backgroundImage,
+                        borderColor: style.borderColor,
+                        padding: style.padding,
+                        margin: style.margin,
+                        cursor: style.cursor,
+                    },
+                };
+            };
+            return {
+                body: measure('body'),
+                container: measure('#container'),
+                topBackBar: measure('body > :first-child'),
+                sectionBar: measure('.section_bar'),
+                formList: measure('.form_list'),
+                firstField: measure('.form_list > .col'),
+                firstInput: measure('input[type="number"]'),
+                firstInfoButton: measure('.form_list button'),
+                controlBar: measure('.control_bar'),
+                resetButton: measure('.reset_btn'),
+                submitButton: measure('.submit_btn'),
+                priorityGrid: measure('.half_section_left'),
+                priorityColumn: measure('.priority-list'),
+                priorityItem: measure('.priority-list .list-group-item'),
+                helpButton: measure('.priority_info button'),
+                document: {
+                    width: document.documentElement.scrollWidth,
+                    height: document.documentElement.scrollHeight,
+                },
+            };
+        });
+        await page.screenshot({
+            path: resolve(artifactRoot, `ref-npc-policy-${viewport.name}.png`),
+            fullPage: true,
+        });
+        await context.close();
+    }
+    await writeFile(resolve(artifactRoot, 'computed-dom.json'), `${JSON.stringify(result, null, 2)}\n`);
+    process.stdout.write(`${JSON.stringify({ ok: true, artifactRoot, viewports: Object.keys(result) })}\n`);
+} finally {
+    await browser.close();
+}

tools/integration-tests/src/turn-differential/coreCommandTrace.ts

@@ -25,6 +25,11 @@ import {
     type CanonicalTurnSnapshot,
 } from './canonical.js';
 
+interface GeneralCooldownSelector {
+    generalId: number;
+    actionName: string;
+}
+
 export interface TurnCommandFixtureRequest {
     kind: 'general' | 'nation';
     actorGeneralId: number;
@@ -47,6 +52,7 @@ export interface TurnCommandFixtureRequest {
         troops?: Array<Record<string, unknown>>;
         diplomacy?: Array<Record<string, unknown>>;
         randomFoundingCandidateCityIds?: number[];
+        generalCooldowns?: Array<GeneralCooldownSelector & { nextAvailableTurn: number }>;
     };
     observe?: {
         generalIds?: number[];
@@ -54,6 +60,7 @@ export interface TurnCommandFixtureRequest {
         nationIds?: number[];
         logAfterId?: number;
         messageAfterId?: number;
+        generalCooldowns?: GeneralCooldownSelector[];
     };
 }
 
@@ -288,6 +295,19 @@ const buildWorldInput = (
     const month = readNumber(referenceBefore.world, 'month', request.setup?.world?.month ?? 1);
     const turnTime = new Date(`${String(year).padStart(4, '0')}-${String(month).padStart(2, '0')}-01T00:00:00.000Z`);
     const generals = referenceBefore.generals.map((row) => buildGeneral(row, turnTime));
+    const referenceGeneralCooldowns = Array.isArray(referenceBefore.world.generalCooldowns)
+        ? referenceBefore.world.generalCooldowns
+        : [];
+    for (const rawCooldown of referenceGeneralCooldowns) {
+        const cooldown = asRecord(rawCooldown);
+        const generalId = readNumber(cooldown, 'generalId');
+        const actionName = readString(cooldown, 'actionName', '');
+        const nextAvailableTurn = cooldown.nextAvailableTurn;
+        const general = generals.find((entry) => entry.id === generalId);
+        if (general && actionName && typeof nextAvailableTurn === 'number' && Number.isFinite(nextAvailableTurn)) {
+            general.meta[`next_execute_${actionName}`] = nextAvailableTurn;
+        }
+    }
     const fixtureNations = new Map((request.setup?.nations ?? []).map((row) => [readNumber(row, 'id'), row] as const));
     const nations = referenceBefore.nations.map((row) =>
         buildNation(
@@ -429,6 +449,7 @@ const projectWorld = (
         generalIds: Set<number>;
         cityIds: Set<number>;
         nationIds: Set<number>;
+        generalCooldowns: GeneralCooldownSelector[];
     }
 ): CanonicalTurnSnapshot => {
     const state = world.getState();
@@ -489,6 +510,15 @@ const projectWorld = (
             tickMinutes: Math.max(1, Math.round(state.tickSeconds / 60)),
             turnTime: state.lastTurnTime.toISOString(),
             isUnited: readNumber(state.meta, 'isUnited'),
+            generalCooldowns: selector.generalCooldowns.map(({ generalId, actionName }) => {
+                const general = world.getGeneralById(generalId);
+                const raw = general?.meta[`next_execute_${actionName}`];
+                return {
+                    generalId,
+                    actionName,
+                    nextAvailableTurn: typeof raw === 'number' && Number.isFinite(raw) ? raw : null,
+                };
+            }),
         },
         generals,
         cities: world
@@ -595,6 +625,7 @@ export const runCoreTurnCommandTrace = async (
         ]),
         cityIds: new Set(referenceBefore.cities.map((row) => readNumber(row, 'id'))),
         nationIds: new Set(referenceBefore.nations.map((row) => readNumber(row, 'id'))),
+        generalCooldowns: request.observe?.generalCooldowns ?? [],
     };
     const reservedTurns = new InMemoryReservedTurnStore(emptyDatabaseClient as never, {
         maxGeneralTurns: 10,

tools/integration-tests/test/tournamentLifecycle.test.ts

@@ -0,0 +1,468 @@
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import { execFile } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { createTRPCProxyClient, httpBatchLink } from '@trpc/client';
+
+import type { AppRouter as GatewayAppRouter } from '@sammo-ts/gateway-api';
+import { createGatewayApiServer } from '@sammo-ts/gateway-api';
+import type { AppRouter as GameAppRouter } from '@sammo-ts/game-api';
+import {
+    buildTournamentKeys,
+    createGameApiServer,
+    DatabaseTurnDaemonTransport,
+    processTournamentTick,
+    TournamentStore,
+} from '@sammo-ts/game-api';
+import { createTurnDaemonRuntime } from '@sammo-ts/game-engine';
+import {
+    createGamePostgresConnector,
+    createGatewayPostgresConnector,
+    createRedisConnector,
+    resolvePostgresConfigFromEnv,
+    resolveRedisConfigFromEnv,
+    type GamePrisma,
+} from '@sammo-ts/infra';
+
+const workspaceRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../..');
+const sleep = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms));
+
+const parseEnvFile = (rawText: string): Record<string, string> => {
+    const env: Record<string, string> = {};
+    for (const line of rawText.split(/\r?\n/)) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith('#')) {
+            continue;
+        }
+        const separator = trimmed.indexOf('=');
+        if (separator < 0) {
+            continue;
+        }
+        const key = trimmed.slice(0, separator).trim();
+        let value = trimmed.slice(separator + 1).trim();
+        if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+            value = value.slice(1, -1);
+        }
+        env[key] = value;
+    }
+    return env;
+};
+
+const loadEnv = async (): Promise<void> => {
+    const values = parseEnvFile(await fs.readFile(path.join(workspaceRoot, '.env.ci'), 'utf8'));
+    for (const [key, value] of Object.entries(values)) {
+        if (process.env[key] === undefined) {
+            process.env[key] = value;
+        }
+    }
+    process.env.INTEGRATION_JOIN_ALLOW_CITY ??= 'true';
+    process.env.INTEGRATION_WORLD_SEED ??= 'tournament-lifecycle-seed';
+};
+
+const execCommand = (command: string, args: string[], env?: NodeJS.ProcessEnv): Promise<void> =>
+    new Promise((resolve, reject) => {
+        execFile(command, args, { env, cwd: workspaceRoot }, (error, stdout, stderr) => {
+            if (error) {
+                reject(new Error(`${command} ${args.join(' ')} failed:\n${stdout}\n${stderr}`));
+                return;
+            }
+            resolve();
+        });
+    });
+
+const ensureSchema = async (schema: string): Promise<void> => {
+    const connector = createGatewayPostgresConnector({
+        url: resolvePostgresConfigFromEnv({ schema: 'public' }).url,
+    });
+    await connector.connect();
+    try {
+        await connector.prisma.$executeRawUnsafe(`CREATE SCHEMA IF NOT EXISTS "${schema}"`);
+    } finally {
+        await connector.disconnect();
+    }
+};
+
+const truncateSchema = async (schema: string): Promise<void> => {
+    const connector = createGatewayPostgresConnector({
+        url: resolvePostgresConfigFromEnv({ schema: 'public' }).url,
+    });
+    await connector.connect();
+    try {
+        const rows = (await connector.prisma.$queryRawUnsafe(
+            `SELECT tablename FROM pg_tables WHERE schemaname = '${schema}'`
+        )) as Array<{ tablename: string }>;
+        if (rows.length === 0) {
+            return;
+        }
+        const tableList = rows.map((row) => `"${schema}"."${row.tablename}"`).join(', ');
+        await connector.prisma.$executeRawUnsafe(`TRUNCATE TABLE ${tableList} RESTART IDENTITY CASCADE`);
+    } finally {
+        await connector.disconnect();
+    }
+};
+
+const resetServices = async (): Promise<void> => {
+    await ensureSchema('public');
+    await ensureSchema('che');
+    await execCommand('pnpm', ['--filter', '@sammo-ts/infra', 'prisma:db:push:gateway', '--accept-data-loss'], {
+        ...process.env,
+        POSTGRES_SCHEMA: 'public',
+    });
+    await execCommand('pnpm', ['--filter', '@sammo-ts/infra', 'prisma:db:push:game', '--accept-data-loss'], {
+        ...process.env,
+        POSTGRES_SCHEMA: 'che',
+    });
+    await truncateSchema('public');
+    await truncateSchema('che');
+
+    const redis = createRedisConnector(resolveRedisConfigFromEnv());
+    await redis.connect();
+    try {
+        await redis.client.flushDb();
+    } finally {
+        await redis.disconnect();
+    }
+};
+
+const createGatewayClient = (baseUrl: string, pathName: string, token: { value?: string }) =>
+    createTRPCProxyClient<GatewayAppRouter>({
+        links: [
+            httpBatchLink({
+                url: `${baseUrl}${pathName}`,
+                headers: () => (token.value ? { 'x-session-token': token.value } : {}),
+            }),
+        ],
+    });
+
+const createGameClient = (baseUrl: string, pathName: string, token: { value?: string }) =>
+    createTRPCProxyClient<GameAppRouter>({
+        links: [
+            httpBatchLink({
+                url: `${baseUrl}${pathName}`,
+                headers: () => (token.value ? { authorization: `Bearer ${token.value}` } : {}),
+            }),
+        ],
+    });
+
+describe('actual tournament lifecycle', () => {
+    let gatewayServer: Awaited<ReturnType<typeof createGatewayApiServer>> | null = null;
+    let gameServer: Awaited<ReturnType<typeof createGameApiServer>> | null = null;
+    let turnDaemon: Awaited<ReturnType<typeof createTurnDaemonRuntime>> | null = null;
+    let turnDaemonLoop: Promise<void> | null = null;
+    let gameConnector: Awaited<ReturnType<typeof createGamePostgresConnector>> | null = null;
+    let redisConnector: Awaited<ReturnType<typeof createRedisConnector>> | null = null;
+    let store: TournamentStore | null = null;
+    let transport: DatabaseTurnDaemonTransport | null = null;
+
+    const clients = new Map<string, ReturnType<typeof createGameClient>>();
+    const generalIds = new Map<string, number>();
+
+    beforeAll(async () => {
+        await loadEnv();
+        process.env.SCENARIO = '908';
+        process.chdir(workspaceRoot);
+        await resetServices();
+
+        gatewayServer = await createGatewayApiServer();
+        await gatewayServer.app.listen({ host: gatewayServer.config.host, port: gatewayServer.config.port });
+        gameServer = await createGameApiServer();
+        await gameServer.app.listen({ host: gameServer.config.host, port: gameServer.config.port });
+
+        const gatewayUrl = `http://localhost:${gatewayServer.config.port}`;
+        const gameUrl = `http://localhost:${gameServer.config.port}`;
+        const adminSession = { value: undefined as string | undefined };
+        const gatewayClient = createGatewayClient(gatewayUrl, gatewayServer.config.trpcPath, adminSession);
+
+        const bootstrap = await gatewayClient.auth.bootstrapLocal.mutate({
+            token: process.env.GATEWAY_BOOTSTRAP_TOKEN ?? '',
+            username: 'admin',
+            password: 'admin-pass-123',
+            displayName: '관리자',
+        });
+        adminSession.value = bootstrap.sessionToken;
+
+        const users = [
+            ['participant', '대회참가자'],
+            ['bettor-a', '베팅유저A'],
+            ['bettor-b', '베팅유저B'],
+            ['no-general', '무장수유저'],
+        ] as const;
+        for (const [username, displayName] of users) {
+            await gatewayClient.admin.users.createLocal.mutate({
+                username,
+                password: `${username}-pass`,
+                displayName,
+            });
+        }
+
+        await gatewayClient.admin.profiles.upsert.mutate({
+            profile: 'che',
+            scenario: '908',
+            apiPort: Number(process.env.GAME_API_PORT ?? 14000),
+            status: 'RUNNING',
+        });
+        await gatewayClient.admin.profiles.installNow.mutate({
+            profileName: 'che:908',
+            install: {
+                scenarioId: 908,
+                turnTermMinutes: 1,
+                sync: false,
+                fiction: 0,
+                extend: true,
+                blockGeneralCreate: 0,
+                npcMode: 0,
+                showImgLevel: 0,
+                tournamentTrig: true,
+                joinMode: 'full',
+                autorunUser: null,
+            },
+        });
+
+        for (const [username, displayName] of users) {
+            const login = await gatewayClient.auth.login.mutate({
+                username,
+                password: `${username}-pass`,
+            });
+            const gatewayToken = await gatewayClient.auth.issueGameSession.mutate({
+                sessionToken: login.sessionToken,
+                profile: 'che:908',
+            });
+            const accessRef = { value: undefined as string | undefined };
+            const client = createGameClient(gameUrl, gameServer.config.trpcPath, accessRef);
+            const access = await client.auth.exchangeGatewayToken.mutate({ gatewayToken: gatewayToken.gameToken });
+            accessRef.value = access.accessToken;
+            clients.set(username, client);
+
+            if (username !== 'no-general') {
+                const created = await client.join.createGeneral.mutate({
+                    name: displayName,
+                    leadership: 55,
+                    strength: 55,
+                    intel: 55,
+                    character: 'Random',
+                });
+                generalIds.set(username, created.generalId);
+            }
+        }
+
+        const gameDatabaseUrl = resolvePostgresConfigFromEnv({ schema: 'che' }).url;
+        const gatewayDatabaseUrl = resolvePostgresConfigFromEnv({ schema: 'public' }).url;
+        gameConnector = createGamePostgresConnector({ url: gameDatabaseUrl });
+        await gameConnector.connect();
+        await gameConnector.prisma.general.updateMany({
+            where: { id: { in: [...generalIds.values()] } },
+            data: { gold: 10_000 },
+        });
+        const maxGeneralId = (await gameConnector.prisma.general.aggregate({ _max: { id: true } }))._max.id ?? 0;
+        const npcTemplate = await gameConnector.prisma.general.findFirstOrThrow({
+            where: { id: { in: [...generalIds.values()] } },
+        });
+        const {
+            id: _templateId,
+            userId: _templateUserId,
+            name: _templateName,
+            createdAt: _templateCreatedAt,
+            updatedAt: _templateUpdatedAt,
+            ...npcTemplateData
+        } = npcTemplate;
+        const templateMeta =
+            typeof npcTemplate.meta === 'object' && npcTemplate.meta !== null && !Array.isArray(npcTemplate.meta)
+                ? npcTemplate.meta
+                : {};
+        await gameConnector.prisma.general.createMany({
+            data: Array.from({ length: 48 }, (_, index): GamePrisma.GeneralCreateManyInput => ({
+                ...npcTemplateData,
+                id: maxGeneralId + index + 1,
+                userId: null,
+                name: `대회NPC${index + 1}`,
+                npcState: 2,
+                leadership: 40 + (index % 31),
+                strength: 40 + ((index * 3) % 31),
+                intel: 40 + ((index * 7) % 31),
+                gold: 10_000,
+                lastTurn: npcTemplate.lastTurn as GamePrisma.InputJsonValue,
+                meta: { ...templateMeta, explevel: 20 },
+                penalty: npcTemplate.penalty as GamePrisma.InputJsonValue,
+            })),
+        });
+
+        redisConnector = createRedisConnector(resolveRedisConfigFromEnv());
+        await redisConnector.connect();
+        store = new TournamentStore(redisConnector.client, buildTournamentKeys('che:908'));
+        transport = new DatabaseTurnDaemonTransport(gameConnector.prisma, 30_000);
+
+        turnDaemon = await createTurnDaemonRuntime({
+            profile: 'che',
+            profileName: 'che:908',
+            databaseUrl: gameDatabaseUrl,
+            gatewayDatabaseUrl,
+            redisUrl: resolveRedisConfigFromEnv().url,
+        });
+
+        for (let attempt = 0; attempt < 36; attempt += 1) {
+            const current = turnDaemon.world.getState().lastTurnTime;
+            const next = new Date(current.getTime());
+            next.setUTCMonth(next.getUTCMonth() + 1);
+            await turnDaemon.world.advanceMonth(next);
+            if ((await store.getState())?.stage === 1) {
+                break;
+            }
+        }
+        expect(await store.getState()).toMatchObject({ stage: 1, auto: true });
+
+        turnDaemonLoop = turnDaemon.lifecycle.start();
+        const status = await transport.requestStatus(10_000);
+        expect(status).not.toBeNull();
+    }, 120_000);
+
+    afterAll(async () => {
+        if (turnDaemon) {
+            await turnDaemon.lifecycle.stop('tournament-lifecycle-test');
+            await turnDaemon.close();
+            await turnDaemonLoop;
+        }
+        await redisConnector?.disconnect();
+        await gameConnector?.disconnect();
+        await gameServer?.app.close();
+        await gatewayServer?.app.close();
+    }, 30_000);
+
+    it('runs auto-open, enrollment, betting, finals, rewards, and payout through the real daemon', async () => {
+        if (!store || !transport || !gameConnector) {
+            throw new Error('integration runtime is not ready');
+        }
+        const participant = clients.get('participant')!;
+        const bettorA = clients.get('bettor-a')!;
+        const bettorB = clients.get('bettor-b')!;
+        const noGeneral = clients.get('no-general')!;
+
+        await expect(noGeneral.tournament.getState.query()).rejects.toThrow();
+        await expect(participant.tournament.join.mutate()).resolves.toMatchObject({ ok: true });
+        await expect(participant.tournament.join.mutate()).resolves.toMatchObject({ ok: true });
+
+        for (let steps = 0; steps < 2000; steps += 1) {
+            const state = await store.getState();
+            if (!state) {
+                throw new Error('tournament state disappeared');
+            }
+            if (state.stage === 6) {
+                break;
+            }
+            await store.setState({
+                ...state,
+                nextAt: new Date(Date.now() - 1_000).toISOString(),
+            });
+            await processTournamentTick({
+                store,
+                prisma: gameConnector.prisma,
+                daemonTransport: transport,
+            });
+        }
+
+        const bettingState = await store.getState();
+        expect(bettingState).toMatchObject({ stage: 6, auto: true });
+        const matches = await store.getMatches();
+        const candidates = Array.from(
+            new Set(
+                matches.filter((match) => match.stage === 7).flatMap((match) => [match.attackerId, match.defenderId])
+            )
+        );
+        expect(candidates).toHaveLength(16);
+
+        const idleDeadline = Date.now() + 60_000;
+        while (Date.now() < idleDeadline) {
+            const pending = await gameConnector.prisma.inputEvent.count({
+                where: { status: { in: ['PENDING', 'PROCESSING'] } },
+            });
+            if (pending === 0) {
+                break;
+            }
+            await sleep(100);
+        }
+        expect(
+            await gameConnector.prisma.inputEvent.count({
+                where: { status: { in: ['PENDING', 'PROCESSING'] } },
+            })
+        ).toBe(0);
+
+        for (const targetId of candidates) {
+            await bettorA.tournament.placeBet.mutate({ targetId, amount: 10 });
+        }
+        await bettorB.tournament.placeBet.mutate({ targetId: candidates[0]!, amount: 100 });
+
+        const bets = await store.getBettingEntries();
+        const bettorAId = generalIds.get('bettor-a')!;
+        const bettorBId = generalIds.get('bettor-b')!;
+        expect(bets.filter((entry) => entry.generalId === bettorAId)).toHaveLength(16);
+        expect(bets.some((entry) => entry.generalId === bettorBId && entry.targetId === candidates[0])).toBe(true);
+        expect(bets.every((entry) => entry.generalId !== generalIds.get('participant'))).toBe(true);
+
+        const bettorBeforeSettlement = await gameConnector.prisma.general.findUniqueOrThrow({
+            where: { id: bettorAId },
+            select: { gold: true, meta: true },
+        });
+
+        await store.setState({
+            ...bettingState!,
+            bettingCloseAt: new Date(Date.now() - 1_000).toISOString(),
+            nextAt: new Date(Date.now() - 1_000).toISOString(),
+        });
+
+        for (let steps = 0; steps < 100; steps += 1) {
+            const state = await store.getState();
+            if (!state) {
+                throw new Error('tournament state disappeared');
+            }
+            if (state.stage === 0 && state.rewardSettled && state.bettingSettled) {
+                break;
+            }
+            if (state.stage > 0) {
+                await store.setState({
+                    ...state,
+                    bettingCloseAt:
+                        state.stage === 6 ? new Date(Date.now() - 1_000).toISOString() : state.bettingCloseAt,
+                    nextAt: new Date(Date.now() - 1_000).toISOString(),
+                });
+            }
+            await processTournamentTick({
+                store,
+                prisma: gameConnector.prisma,
+                daemonTransport: transport,
+            });
+        }
+
+        const finalState = await store.getState();
+        expect(finalState).toMatchObject({
+            stage: 0,
+            auto: false,
+            rewardSettled: true,
+            bettingSettled: true,
+        });
+        expect(finalState?.winnerId).toBeTypeOf('number');
+
+        const bettorAfterSettlement = await gameConnector.prisma.general.findUniqueOrThrow({
+            where: { id: bettorAId },
+            select: { gold: true, meta: true },
+        });
+        expect(bettorAfterSettlement.gold).toBeGreaterThan(bettorBeforeSettlement.gold);
+        expect(bettorAfterSettlement.meta).toMatchObject({
+            betgold: 160,
+            betwin: 1,
+        });
+        expect(Number((bettorAfterSettlement.meta as Record<string, unknown>).betwingold)).toBeGreaterThan(0);
+
+        const settlementEvents = await gameConnector.prisma.inputEvent.findMany({
+            where: { eventType: { in: ['tournamentReward', 'tournamentBettingPayout'] } },
+            select: { eventType: true, status: true, result: true },
+        });
+        expect(settlementEvents).toEqual(
+            expect.arrayContaining([
+                expect.objectContaining({ eventType: 'tournamentReward', status: 'SUCCEEDED' }),
+                expect.objectContaining({ eventType: 'tournamentBettingPayout', status: 'SUCCEEDED' }),
+            ])
+        );
+        expect(settlementEvents.every((event) => (event.result as { ok?: boolean } | null)?.ok === true)).toBe(true);
+    }, 120_000);
+});

tools/integration-tests/test/turnCommandGeneralMatrix.integration.test.ts

@@ -931,6 +931,184 @@ integration('general command pre-required turn boundary matrix', () => {
     );
 });
 
+const readGeneralCooldown = (
+    snapshot: { world: Record<string, unknown> },
+    generalId: number,
+    actionName: string
+): number | null => {
+    const cooldowns = Array.isArray(snapshot.world.generalCooldowns) ? snapshot.world.generalCooldowns : [];
+    const matched = cooldowns.find(
+        (entry) =>
+            typeof entry === 'object' &&
+            entry !== null &&
+            (entry as Record<string, unknown>).generalId === generalId &&
+            (entry as Record<string, unknown>).actionName === actionName
+    );
+    const value =
+        typeof matched === 'object' && matched !== null ? (matched as Record<string, unknown>).nextAvailableTurn : null;
+    return typeof value === 'number' ? value : null;
+};
+
+integration('general command post-required cooldown boundary matrix', () => {
+    it('stores the same 60-turn cooldown after domestic trait reset completion', async () => {
+        const request = buildRequest('che_내정특기초기화', undefined, {
+            specialDomestic: 'che_인덕',
+            lastTurn: { command: '내정 특기 초기화', term: 1 },
+        });
+        request.observe!.generalCooldowns = [{ generalId: 1, actionName: '내정 특기 초기화' }];
+        const reference = runReferenceTurnCommandTraceRequest(
+            workspaceRoot!,
+            request as unknown as Record<string, unknown>
+        );
+        const core = await runCoreTurnCommandTrace(request, reference.before);
+        const expectedNextAvailableTurn = 190 * 12 + 1 - 1 + 60 - 1;
+
+        expect(reference.execution.outcome).toMatchObject({ completed: true });
+        expect(core.execution.outcome).toMatchObject({
+            requestedAction: 'che_내정특기초기화',
+            actionKey: 'che_내정특기초기화',
+            usedFallback: false,
+        });
+        expect(readGeneralCooldown(reference.after, 1, '내정 특기 초기화')).toBe(expectedNextAvailableTurn);
+        expect(readGeneralCooldown(core.after, 1, '내정 특기 초기화')).toBe(expectedNextAvailableTurn);
+        expect(core.rng).toEqual(reference.rng);
+        expect(
+            compareTurnSnapshotDeltas(reference.before, reference.after, core.before, core.after, {
+                ignoredPathPatterns: ignoredLifecyclePaths,
+            })
+        ).toEqual([]);
+    }, 120_000);
+
+    it('blocks domestic trait reset one turn before the cooldown boundary', async () => {
+        const currentYearMonth = 190 * 12 + 1 - 1;
+        const request = buildRequest('che_내정특기초기화', undefined, {
+            specialDomestic: 'che_인덕',
+            lastTurn: { command: '내정 특기 초기화', term: 1 },
+        });
+        request.setup!.generalCooldowns = [
+            {
+                generalId: 1,
+                actionName: '내정 특기 초기화',
+                nextAvailableTurn: currentYearMonth + 1,
+            },
+        ];
+        request.observe!.generalCooldowns = [{ generalId: 1, actionName: '내정 특기 초기화' }];
+        const reference = runReferenceTurnCommandTraceRequest(
+            workspaceRoot!,
+            request as unknown as Record<string, unknown>
+        );
+        const core = await runCoreTurnCommandTrace(request, reference.before);
+
+        expect(readGeneralCooldown(reference.before, 1, '내정 특기 초기화')).toBe(currentYearMonth + 1);
+        expect(readGeneralCooldown(core.before, 1, '내정 특기 초기화')).toBe(currentYearMonth + 1);
+        expect(reference.execution.outcome).toMatchObject({ completed: false });
+        expect(core.execution.outcome).toMatchObject({
+            requestedAction: 'che_내정특기초기화',
+            actionKey: '휴식',
+            usedFallback: true,
+            blockedReason: '1턴 더 기다려야 합니다',
+        });
+        expect(reference.after.logs.some((entry) => String(entry.text).includes('1턴 더 기다려야 합니다'))).toBe(true);
+        expect(core.after.logs.some((entry) => String(entry.text).includes('1턴 더 기다려야 합니다'))).toBe(true);
+        expect(readGeneralCooldown(reference.after, 1, '내정 특기 초기화')).toBe(currentYearMonth + 1);
+        expect(readGeneralCooldown(core.after, 1, '내정 특기 초기화')).toBe(currentYearMonth + 1);
+        expect(core.rng).toEqual(reference.rng);
+        expect(
+            compareTurnSnapshotDeltas(reference.before, reference.after, core.before, core.after, {
+                ignoredPathPatterns: ignoredLifecyclePaths,
+            })
+        ).toEqual([]);
+    }, 120_000);
+
+    it('allows war trait reset exactly at the cooldown boundary', async () => {
+        const currentYearMonth = 190 * 12 + 1 - 1;
+        const request = buildRequest('che_전투특기초기화', undefined, {
+            specialWar: 'che_귀병',
+            lastTurn: { command: '전투 특기 초기화', term: 1 },
+        });
+        request.setup!.generalCooldowns = [
+            {
+                generalId: 1,
+                actionName: '전투 특기 초기화',
+                nextAvailableTurn: currentYearMonth,
+            },
+        ];
+        request.observe!.generalCooldowns = [{ generalId: 1, actionName: '전투 특기 초기화' }];
+        const reference = runReferenceTurnCommandTraceRequest(
+            workspaceRoot!,
+            request as unknown as Record<string, unknown>
+        );
+        const core = await runCoreTurnCommandTrace(request, reference.before);
+        const expectedNextAvailableTurn = currentYearMonth + 60 - 1;
+
+        expect(reference.execution.outcome).toMatchObject({ completed: true });
+        expect(core.execution.outcome).toMatchObject({
+            requestedAction: 'che_전투특기초기화',
+            actionKey: 'che_전투특기초기화',
+            usedFallback: false,
+        });
+        expect(readGeneralCooldown(reference.after, 1, '전투 특기 초기화')).toBe(expectedNextAvailableTurn);
+        expect(readGeneralCooldown(core.after, 1, '전투 특기 초기화')).toBe(expectedNextAvailableTurn);
+        expect(core.rng).toEqual(reference.rng);
+        expect(
+            compareTurnSnapshotDeltas(reference.before, reference.after, core.before, core.after, {
+                ignoredPathPatterns: ignoredLifecyclePaths,
+            })
+        ).toEqual([]);
+    }, 120_000);
+});
+
+const missingTargetCases: Array<{ name: string; action: string; args: Record<string, unknown> }> = [
+    {
+        name: 'gift to a missing general',
+        action: 'che_증여',
+        args: { isGold: true, amount: 100, destGeneralID: 999 },
+    },
+    {
+        name: 'spy on a missing city',
+        action: 'che_첩보',
+        args: { destCityID: 999 },
+    },
+    {
+        name: 'move to a missing city',
+        action: 'che_이동',
+        args: { destCityID: 999 },
+    },
+    {
+        name: 'employ a missing general',
+        action: 'che_등용',
+        args: { destGeneralID: 999 },
+    },
+];
+
+integration('general command missing-target fallback matrix', () => {
+    it.each(missingTargetCases)(
+        '$name rejects the missing target and falls back without command RNG',
+        async ({ action, args }) => {
+            const request = buildRequest(action, args);
+            const reference = runReferenceTurnCommandTraceRequest(
+                workspaceRoot!,
+                request as unknown as Record<string, unknown>
+            );
+            const core = await runCoreTurnCommandTrace(request, reference.before);
+
+            expect(reference.execution.outcome).toMatchObject({ completed: false });
+            expect(core.execution.outcome).toMatchObject({
+                requestedAction: action,
+                actionKey: '휴식',
+                usedFallback: true,
+            });
+            expect(core.rng).toEqual(reference.rng);
+            expect(
+                compareTurnSnapshotDeltas(reference.before, reference.after, core.before, core.after, {
+                    ignoredPathPatterns: ignoredLifecyclePaths,
+                })
+            ).toEqual([]);
+        },
+        120_000
+    );
+});
+
 type GeneralConstraintCase = {
     name: string;
     action: string;