Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

fix(usage): distinguish Codex sessions from fallback render groups

[._.]/ Adam Eivyf7107b08792f
diff --git a/client/src/pages/UsagePage.jsx b/client/src/pages/UsagePage.jsx
index d297868d51..2882f41283 100644
--- a/client/src/pages/UsagePage.jsx
+++ b/client/src/pages/UsagePage.jsx
@@ -709,7 +709,7 @@ function InternalUsageMetrics() {
<section className="bg-port-card border border-port-border rounded-xl p-3 sm:p-4 space-y-2" aria-label="Codex image usage">
<h3 className="text-sm font-medium text-white">Codex image usage · this machine</h3>
<p className="text-sm text-gray-300">
- {formatCount(usage.imageRenders.renderSessions)} render sessions · {formatCount(usage.imageRenders.savedOutputs)} saved outputs in this period
+ {formatCount(usage.imageRenders.codexSessions)} Codex sessions · {formatCount(usage.imageRenders.savedOutputs)} saved outputs in this period
</p>
<p className="text-xs text-gray-400">
Image tokens, image cost and subscription allowance attribution: unknown.
@@ -721,10 +721,10 @@ function InternalUsageMetrics() {
{usage.imageRenders.driverTokens
? `${formatCount(usage.imageRenders.driverTokens.reportedTotal)} reported driver tokens across ${formatCount(usage.imageRenders.driverTokens.sessionsMeasured)} sessions; no input/output split or image attribution.`
: 'Driver tokens: unknown.'}
- {usage.imageRenders.driverTokens && ` Driver tokens are unknown for ${formatCount(usage.imageRenders.driverSessionsUnknown)} other sessions.`}
+ {usage.imageRenders.driverTokens && ` Driver tokens are unknown for ${formatCount(usage.imageRenders.driverSessionsUnknown)} other render groups.`}
</p>
- {usage.imageRenders.jobIdentitySessions > 0 && (
- <p className="text-xs text-gray-400">{formatCount(usage.imageRenders.jobIdentitySessions)} sessions use a saved job identity because the provider session ID is unavailable.</p>
+ {usage.imageRenders.jobIdentityGroups > 0 && (
+ <p className="text-xs text-gray-400">{formatCount(usage.imageRenders.jobIdentityGroups)} additional render groups use saved job IDs; their Codex session IDs are unavailable.</p>
)}
</section>
)}
diff --git a/client/src/pages/UsagePage.test.jsx b/client/src/pages/UsagePage.test.jsx
index 923959477e..a804ff11c5 100644
--- a/client/src/pages/UsagePage.test.jsx
+++ b/client/src/pages/UsagePage.test.jsx
@@ -661,13 +661,13 @@ describe('UsagePage report range freshness (#10687)', () => {
describe('UsagePage image accounting', () => {
it('shows saved render activity separately from unknown image cost and allowance', async () => {
- api.getUsage.mockResolvedValue({ ...usage, imageRenders: { renderSessions: 8, savedOutputs: 10, jobIdentitySessions: 2, imageCostUsd: null } });
+ api.getUsage.mockResolvedValue({ ...usage, imageRenders: { renderGroups: 8, codexSessions: 6, savedOutputs: 10, jobIdentityGroups: 2, imageCostUsd: null } });
render(<MemoryRouter><UsagePage /></MemoryRouter>);
const card = await screen.findByRole('region', { name: 'Codex image usage' });
- expect(within(card).getByText(/8 render sessions · 10 saved outputs/)).toBeInTheDocument();
+ expect(within(card).getByText(/6 Codex sessions · 10 saved outputs/)).toBeInTheDocument();
expect(within(card).getByText(/Image tokens, image cost and subscription allowance attribution: unknown/)).toBeInTheDocument();
expect(within(card).queryByText(/\$0/)).not.toBeInTheDocument();
- expect(within(card).getByText(/2 sessions use a saved job identity/)).toBeInTheDocument();
+ expect(within(card).getByText(/2 additional render groups use saved job IDs/)).toBeInTheDocument();
const reads = api.getUsage.mock.calls.length;
await act(async () => { socket.emit('image-gen:completed', { mode: 'codex' }); });
await waitFor(() => expect(api.getUsage.mock.calls.length).toBe(reads + 1));
diff --git a/docs/STORAGE.md b/docs/STORAGE.md
index f90e123561..d0385988d3 100644
--- a/docs/STORAGE.md
+++ b/docs/STORAGE.md
@@ -1239,7 +1239,9 @@ FableLoom shot-planning run checkpoints live in machine-local `data/fableloom-sh
`data/image-render-usage/<sha256>.json` is a machine-local `file-primary`
accounting receipt ledger (`server/services/imageRenderUsage.js`). Each immutable
receipt describes one saved original output; `renderKey` groups outputs from the
-same Codex session. The Usage page counts sessions separately from saved outputs.
+same Codex session. The Usage page counts real Codex session IDs separately from saved outputs and
+fallback PortOS job groups. A combined render-group total is never presented as
+a count of known Codex sessions.
A missing provider session ID uses the original PortOS job identity and is
reported as such. These are observed saved render sessions, not a count of every
image-tool invocation, attempt or billable image.
diff --git a/server/routes/usage.test.js b/server/routes/usage.test.js
index 327622db43..5e3dc1e18e 100644
--- a/server/routes/usage.test.js
+++ b/server/routes/usage.test.js
@@ -3,7 +3,7 @@ import express from 'express';
import { request } from '../lib/testHelper.js';
import { errorMiddleware } from '../lib/errorHandler.js';
-vi.mock('../services/imageRenderUsage.js', () => ({ getImageRenderUsage: vi.fn(async () => ({ renderSessions: 2, savedOutputs: 3, imageCostUsd: null })) }));
+vi.mock('../services/imageRenderUsage.js', () => ({ getImageRenderUsage: vi.fn(async () => ({ renderGroups: 2, codexSessions: 2, jobIdentityGroups: 0, savedOutputs: 3, imageCostUsd: null })) }));
vi.mock('../services/usage.js', () => ({
getUsageSummary: vi.fn(),
@@ -85,7 +85,7 @@ describe('usage routes', () => {
const response = await request(buildApp()).get('/api/usage?from=2026-07-01&to=2026-07-31');
expect(response.status).toBe(200);
expect(getImageRenderUsage).toHaveBeenCalledWith({ from: '2026-07-01', to: '2026-07-31' });
- expect(response.body.imageRenders).toEqual({ renderSessions: 2, savedOutputs: 3, imageCostUsd: null });
+ expect(response.body.imageRenders).toEqual({ renderGroups: 2, codexSessions: 2, jobIdentityGroups: 0, savedOutputs: 3, imageCostUsd: null });
expect(response.body.report.totals.estimatedCost).toBe(12);
});
@@ -146,7 +146,7 @@ describe('usage routes', () => {
providers: ['anthropic'],
subscriptionSavings: { configured: false, families: [] },
fleet: { instances: [], totals: null },
- imageRenders: { renderSessions: 2, savedOutputs: 3, imageCostUsd: null },
+ imageRenders: { renderGroups: 2, codexSessions: 2, jobIdentityGroups: 0, savedOutputs: 3, imageCostUsd: null },
monthlyHistory: [],
monthlySeries: [],
monthlyInstanceCount: 1,
diff --git a/server/services/imageGen/codex.test.js b/server/services/imageGen/codex.test.js
index ebab0f2b6f..b7ff55c624 100644
--- a/server/services/imageGen/codex.test.js
+++ b/server/services/imageGen/codex.test.js
@@ -479,7 +479,7 @@ describe('codex provider — image harvest', () => {
expect(Buffer.compare(written, fakePngBytes)).toBe(0);
const { getImageRenderUsage } = await import('../imageRenderUsage.js');
- expect(await getImageRenderUsage()).toMatchObject({ renderSessions: 1, savedOutputs: 1, imageCostUsd: null, driverTokens: { reportedTotal: 1234, sessionsMeasured: 1 } });
+ expect(await getImageRenderUsage()).toMatchObject({ renderGroups: 1, savedOutputs: 1, imageCostUsd: null, driverTokens: { reportedTotal: 1234, sessionsMeasured: 1 } });
// Sidecar metadata exists too.
const sidecar = join(FAKE_IMAGES_DIR, `${job.generationId}.metadata.json`);
diff --git a/server/services/imageRenderBackfill.js b/server/services/imageRenderBackfill.js
index e711c591c4..dc86a63901 100644
--- a/server/services/imageRenderBackfill.js
+++ b/server/services/imageRenderBackfill.js
@@ -56,7 +56,9 @@ export async function planImageRenderBackfill(dataDir) {
version: 1, inventoryHash: hash(receipts), receipts,
coverage: {
...coverage, eligibleOutputs: receipts.length,
- renderSessions: new Set(receipts.map(row => row.renderKey)).size,
+ renderGroups: new Set(receipts.map(row => row.renderKey)).size,
+ codexSessions: new Set(receipts.filter(row => row.identitySource === 'codex-session').map(row => row.renderKey)).size,
+ jobIdentityGroups: new Set(receipts.filter(row => row.identitySource === 'portos-job').map(row => row.renderKey)).size,
jobIdentityOutputs: receipts.filter(row => row.identitySource === 'portos-job').length,
alreadyRecorded: receipts.length - pending.length, additiveOutputs: pending.length,
earliest: receipts.map(row => row.occurredAt).sort()[0] || null,
diff --git a/server/services/imageRenderBackfill.test.js b/server/services/imageRenderBackfill.test.js
index 1fc06fd811..d04a325e80 100644
--- a/server/services/imageRenderBackfill.test.js
+++ b/server/services/imageRenderBackfill.test.js
@@ -31,14 +31,14 @@ describe('saved Codex image usage recovery', () => {
await sidecar('other-provider', { mode: 'agy' });
await writeFile(join(root, 'media-jobs.json'), JSON.stringify({ jobs: [{ kind: 'image', status: 'completed', params: { mode: 'codex' }, result: { filename: 'original.png', generationId: id }, startedAt: '2026-07-01T12:00:00Z' }] }));
const plan = await planImageRenderBackfill(root);
- expect(plan.coverage).toMatchObject({ eligibleOutputs: 2, renderSessions: 1, duplicates: 1, derived: 2, unrecoverable: 1, queueOnly: 0 });
+ expect(plan.coverage).toMatchObject({ eligibleOutputs: 2, renderGroups: 1, duplicates: 1, derived: 2, unrecoverable: 1, queueOnly: 0 });
expect(JSON.stringify(plan)).not.toContain('Private example prompt');
expect(await readdir(root)).not.toContain('image-render-usage');
const applied = await applyImageRenderBackfill(root, plan, join(root, 'journal.json'));
expect(applied.inserted).toBe(2);
expect((await applyImageRenderBackfill(root, plan, join(root, 'second-journal.json'))).inserted).toBe(0);
- expect(await getImageRenderUsage({ directory, from: '2026-07-01', to: '2026-07-01' })).toMatchObject({ renderSessions: 1, savedOutputs: 2, imageTokens: null, imageCostUsd: null, allowanceUnits: null, driverTokens: null });
- expect(await getImageRenderUsage({ directory, from: '2026-07-02' })).toMatchObject({ renderSessions: 0, savedOutputs: 0 });
+ expect(await getImageRenderUsage({ directory, from: '2026-07-01', to: '2026-07-01' })).toMatchObject({ renderGroups: 1, codexSessions: 1, jobIdentityGroups: 0, savedOutputs: 2, imageTokens: null, imageCostUsd: null, allowanceUnits: null, driverTokens: null });
+ expect(await getImageRenderUsage({ directory, from: '2026-07-02' })).toMatchObject({ renderGroups: 0, savedOutputs: 0 });
expect(await readFile(join(root, 'usage.json'), 'utf8')).toBe('{"existing":"preserve exactly"}');
const journal = JSON.parse(await readFile(join(root, 'journal.json'), 'utf8'));
expect((await readRenderReceipts({ directory })).every(row => row.backfillBatch === journal.batch)).toBe(true);
@@ -51,8 +51,8 @@ describe('saved Codex image usage recovery', () => {
await expect(applyImageRenderBackfill(root, oldPlan, join(root, 'journal.json'))).rejects.toThrow('inventory changed');
const plan = await planImageRenderBackfill(root);
await applyImageRenderBackfill(root, plan, join(root, 'journal.json'));
- expect(await getImageRenderUsage({ directory, from: '2026-07-01', to: '2026-07-01' })).toMatchObject({ renderSessions: 1, savedOutputs: 2 });
- expect(await getImageRenderUsage({ directory, from: '2026-07-02' })).toMatchObject({ renderSessions: 0, savedOutputs: 0 });
+ expect(await getImageRenderUsage({ directory, from: '2026-07-01', to: '2026-07-01' })).toMatchObject({ renderGroups: 1, savedOutputs: 2 });
+ expect(await getImageRenderUsage({ directory, from: '2026-07-02' })).toMatchObject({ renderGroups: 0, savedOutputs: 0 });
});
it('publishes complete receipts exactly once across simultaneous writers and does not replace a live receipt during backfill', async () => {
diff --git a/server/services/imageRenderUsage.js b/server/services/imageRenderUsage.js
index df5ed1d361..7b152ac182 100644
--- a/server/services/imageRenderUsage.js
+++ b/server/services/imageRenderUsage.js
@@ -124,7 +124,7 @@ export async function getImageRenderUsage({ from = null, to = null, directory }
if (session.driverTotal !== null) { driverSessionsMeasured++; driverReportedTotal += session.driverTotal; }
}
return {
- scope: 'local-codex-saved-renders', renderSessions, savedOutputs, jobIdentitySessions,
+ scope: 'local-codex-saved-renders', renderGroups: renderSessions, codexSessions: renderSessions - jobIdentitySessions, savedOutputs, jobIdentityGroups: jobIdentitySessions,
driverTokens: driverSessionsMeasured ? { reportedTotal: driverReportedTotal, sessionsMeasured: driverSessionsMeasured } : null,
driverSessionsUnknown: renderSessions - driverSessionsMeasured,
imageTokens: null, imageCostUsd: null, allowanceUnits: null,