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): isolate image ledger errors and deduplicate queue recovery

[._.]/ Adam Eivy149d3af2792f
diff --git a/client/src/pages/UsagePage.jsx b/client/src/pages/UsagePage.jsx
index 2882f41283..bed85749e4 100644
--- a/client/src/pages/UsagePage.jsx
+++ b/client/src/pages/UsagePage.jsx
@@ -708,6 +708,10 @@ function InternalUsageMetrics() {
{usage.imageRenders && (
<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>
+ {usage.imageRenders.error ? (
+ <p className="text-sm text-gray-400" role="status">Image render usage is unavailable. Text usage remains available.</p>
+ ) : (
+ <>
<p className="text-sm text-gray-300">
{formatCount(usage.imageRenders.codexSessions)} Codex sessions · {formatCount(usage.imageRenders.savedOutputs)} saved outputs in this period
</p>
@@ -726,6 +730,8 @@ function InternalUsageMetrics() {
{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 a804ff11c5..c0688310b9 100644
--- a/client/src/pages/UsagePage.test.jsx
+++ b/client/src/pages/UsagePage.test.jsx
@@ -660,6 +660,15 @@ describe('UsagePage report range freshness (#10687)', () => {
describe('UsagePage image accounting', () => {
+ it('shows image accounting as unavailable without hiding the text report or inventing zero usage', async () => {
+ api.getUsage.mockResolvedValue({ ...usage, report: { ...usage.report, totals: { estimatedCost: 12 } }, imageRenders: { error: 'Image render usage is unavailable.' } });
+ render(<MemoryRouter><UsagePage /></MemoryRouter>);
+ const card = await screen.findByRole('region', { name: 'Codex image usage' });
+ expect(within(card).getByRole('status')).toHaveTextContent('Image render usage is unavailable. Text usage remains available.');
+ expect(within(card).queryByText(/saved outputs|\$0/)).not.toBeInTheDocument();
+ expect(screen.getAllByText('$12.00').length).toBeGreaterThan(0);
+ });
+
it('shows saved render activity separately from unknown image cost and allowance', async () => {
api.getUsage.mockResolvedValue({ ...usage, imageRenders: { renderGroups: 8, codexSessions: 6, savedOutputs: 10, jobIdentityGroups: 2, imageCostUsd: null } });
render(<MemoryRouter><UsagePage /></MemoryRouter>);
diff --git a/docs/STORAGE.md b/docs/STORAGE.md
index d0385988d3..efe98f9a1b 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 real Codex session IDs separately from saved outputs and
+same Codex session. Output identity uses the PortOS job ID when available,
+independently of session attribution, so queue-only recovery cannot add a
+previously recorded live output again. 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
@@ -1251,7 +1253,8 @@ record editing or cross-domain joins. Receipts publish complete files with an
exclusive hard link, so a live completion and an explicit backfill cannot replace
one another or double-count an output across processes. Hidden temporary files
are ignored after an interrupted write. A damaged receipt fails the read rather
-than reporting a trustworthy zero. Rsync backs up this directory by default; it
+than reporting a trustworthy zero. The Usage endpoint contains that failure to
+the image card, which reports unavailable while text accounting remains visible. Rsync backs up this directory by default; it
is not a peer-usage digest or a media-library asset and does not federate.
Receipts contain hashed identities, the original saved timestamp, driver model
diff --git a/server/routes/usage.js b/server/routes/usage.js
index 7d248cdaf8..826f1a3339 100644
--- a/server/routes/usage.js
+++ b/server/routes/usage.js
@@ -55,7 +55,10 @@ router.get('/', asyncHandler(async (req, res) => {
getApiBilledInstanceIds().then((apiBilledInstanceIds) =>
getFleetUsage({ from, to, providers, apiBilledInstanceIds })),
getFleetMonthlyUsage({ providers }),
- getImageRenderUsage({ from, to }),
+ getImageRenderUsage({ from, to }).catch(err => {
+ console.error(`❌ Failed to read image render usage: ${err.message}`);
+ return { error: 'Image render usage is unavailable.' };
+ }),
]);
res.json({
...summary, subscriptionSavings, fleet, imageRenders,
diff --git a/server/routes/usage.test.js b/server/routes/usage.test.js
index 5e3dc1e18e..7a8a2c7d4a 100644
--- a/server/routes/usage.test.js
+++ b/server/routes/usage.test.js
@@ -89,6 +89,19 @@ describe('usage routes', () => {
expect(response.body.report.totals.estimatedCost).toBe(12);
});
+ it('keeps text reporting available when the optional image ledger is damaged', async () => {
+ usage.getUsageSummary.mockReturnValue({ report: { totals: { estimatedCost: 12 } } });
+ getImageRenderUsage.mockRejectedValueOnce(new Error('Invalid image render usage receipt'));
+ const logged = vi.spyOn(console, 'error').mockImplementation(() => {});
+ try {
+ const response = await request(buildApp()).get('/api/usage');
+ expect(response.status).toBe(200);
+ expect(response.body.report.totals.estimatedCost).toBe(12);
+ expect(response.body.imageRenders).toEqual({ error: 'Image render usage is unavailable.' });
+ expect(logged).toHaveBeenCalled();
+ } finally { logged.mockRestore(); }
+ });
+
it('GET /api/usage/hourly projects only counters and bypasses all reporting work', async () => {
const hourlyActivity = Array.from({ length: 24 }, (_, hour) => hour);
// Synthetic extra records must never escape in the hourly payload. Reporting
diff --git a/server/services/imageRenderBackfill.test.js b/server/services/imageRenderBackfill.test.js
index 168a2d19f1..51aaa50b7c 100644
--- a/server/services/imageRenderBackfill.test.js
+++ b/server/services/imageRenderBackfill.test.js
@@ -67,6 +67,17 @@ describe('saved Codex image usage recovery', () => {
expect(codexDriverReportedTokens('no footer')).toBeNull();
});
+ it('does not count a live receipt again when only completed queue metadata remains', async () => {
+ await recordRenderReceipt(codexRenderReceipt(meta()), { directory });
+ await writeFile(join(root, 'media-jobs.json'), JSON.stringify({ jobs: [
+ { kind: 'image', status: 'completed', params: { mode: 'codex' }, result: { filename: 'deleted.png', generationId: id }, startedAt: '2026-07-01T12:00:00Z' },
+ ] }));
+ const plan = await planImageRenderBackfill(root);
+ expect(plan.coverage).toMatchObject({ alreadyRecorded: 1, additiveOutputs: 0, queueOnly: 1 });
+ expect((await applyImageRenderBackfill(root, plan, join(root, 'journal.json'))).inserted).toBe(0);
+ expect(await getImageRenderUsage({ directory })).toMatchObject({ savedOutputs: 1, codexSessions: 1, jobIdentityGroups: 0 });
+ });
+
it('uses completed queue evidence for deleted sidecars and keeps missing identities or timestamps unrecoverable', async () => {
await writeFile(join(root, 'media-jobs.json'), JSON.stringify({ jobs: [
{ kind: 'image', status: 'completed', params: { mode: 'codex' }, result: { filename: 'deleted.png', generationId: id }, startedAt: '2026-06-01T01:02:03Z' },
diff --git a/server/services/imageRenderUsage.js b/server/services/imageRenderUsage.js
index d0476808c3..e08ac803cb 100644
--- a/server/services/imageRenderUsage.js
+++ b/server/services/imageRenderUsage.js
@@ -26,7 +26,7 @@ export function codexRenderReceipt(meta) {
if (!occurredAt) return null;
const renderKey = digest(`codex:${session || job}`);
// Without a job id, a recovered tool call supplies a stable output identity.
- const outputKey = digest(`${renderKey}:${job || meta.codexCallId || 'saved-output'}`);
+ const outputKey = digest(job ? `codex-job:${job.toLowerCase()}` : `${renderKey}:${meta.codexCallId || 'saved-output'}`);
return {
version: 1, id: outputKey, renderKey, occurredAt,
timestampSource: timestamp(meta.renderStartedAt) ? 'renderStartedAt' : 'createdAt',
@@ -91,7 +91,7 @@ export async function recordRenderReceipt(receipt, { directory = ledgerDir() } =
if (await publishAccountingFile(path, receipt)) return true;
existing = JSON.parse(await readFile(path, 'utf8'));
}
- if (existing?.id !== receipt.id || existing.renderKey !== receipt.renderKey || existing.version !== 1) throw new Error('Conflicting image render receipt');
+ if (existing?.id !== receipt.id || !/^[a-f0-9]{64}$/.test(existing.renderKey) || existing.version !== 1) throw new Error('Conflicting image render receipt');
return false;
}