socialcli 0.3.2__tar.gz → 0.3.3__tar.gz

{socialcli-0.3.2 → socialcli-0.3.3}/LICENSE

@@ -1,7 +1,7 @@
 SocialCli Proprietary Software License
-Version 1 — October 24, 2026
-Copyright (c) 2026 Engels Florentino. All rights reserved.
-SocialCli is operated by Florentino.pro.
+Version 1.1 — October 24, 2026
+Copyright (c) 2026 Florentino.pro. All rights reserved.
+Florentino.pro is the copyright holder, licensor and operator of SocialCli.
 
 1. Scope
 This license applies to SocialCli releases beginning with version 0.3.2 and

{socialcli-0.3.2 → socialcli-0.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: socialcli
-Version: 0.3.2
+Version: 0.3.3
 Summary: SocialCli: publish and manage creator-owned social content from the terminal.
 Project-URL: Homepage, https://socialcli.app
 Project-URL: Documentation, https://socialcli.app/ai-agents.html
@@ -22,7 +22,7 @@ Description-Content-Type: text/markdown
 
 # SocialCli
 
-**Current stable version: 0.3.1 (published on PyPI). Source preparation: 0.3.2.** SocialCli SaaS is the current SocialCli
+**Current stable version: 0.3.2 (published on PyPI).** SocialCli SaaS is the current SocialCli
 product. The repository root on `main` is its single development workspace;
 the CLI, hosted connection service and account/billing components live together
 here. Earlier versions remain in Git history for reference and migration.
@@ -58,7 +58,7 @@ Stripe uses test mode. Planned access costs
 USD 10/month after 14 free days from the first successful connection. No real
 subscriptions are collected in this pilot.
 
-The current stable client is **0.3.1**, published on TestPyPI and PyPI after
+The current stable client is **0.3.2**, published on TestPyPI and PyPI after
 reviewed CI, matching artifact hashes and clean-install verification.
 The hosted service is managed and verified separately from the CLI release. The client's wheel and
 source archive are verified against the

{socialcli-0.3.2 → socialcli-0.3.3}/README.md

@@ -2,7 +2,7 @@
 
 # SocialCli
 
-**Current stable version: 0.3.1 (published on PyPI). Source preparation: 0.3.2.** SocialCli SaaS is the current SocialCli
+**Current stable version: 0.3.2 (published on PyPI).** SocialCli SaaS is the current SocialCli
 product. The repository root on `main` is its single development workspace;
 the CLI, hosted connection service and account/billing components live together
 here. Earlier versions remain in Git history for reference and migration.
@@ -38,7 +38,7 @@ Stripe uses test mode. Planned access costs
 USD 10/month after 14 free days from the first successful connection. No real
 subscriptions are collected in this pilot.
 
-The current stable client is **0.3.1**, published on TestPyPI and PyPI after
+The current stable client is **0.3.2**, published on TestPyPI and PyPI after
 reviewed CI, matching artifact hashes and clean-install verification.
 The hosted service is managed and verified separately from the CLI release. The client's wheel and
 source archive are verified against the

{socialcli-0.3.2 → socialcli-0.3.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "socialcli"
-version = "0.3.2"
+version = "0.3.3"
 description = "SocialCli: publish and manage creator-owned social content from the terminal."
 readme = "README.md"
 license = "LicenseRef-SocialCli-Proprietary"

{socialcli-0.3.2 → socialcli-0.3.3}/socialctl/agent_errors.py

@@ -61,6 +61,10 @@ _CATALOG = {
     'rate_limited': ('retry_later', 'Wait for the provider rate limit before a bounded read retry.'),
     'authorization_unavailable': ('user_action', 'Review the account authorization; this failure alone does not prove token expiry.'),
     'permissions_required': ('user_action', 'Review granted permissions and account eligibility with the owner.'),
+    'private_video_comments_disabled': ('inspect', 'YouTube disables comments on private videos. No settings were changed. Choose an eligible video; do not change privacy without owner approval.'),
+    'pilot_evidence_required': ('correct_input', 'Pilot evidence is required before persisting this API job. Run native-schedule pilot-template and preflight --eligibility FILE.'),
+    'pilot_evidence_invalid': ('correct_input', 'The pilot eligibility file must match this account and reference an actual nonempty evidence file inside the brand workspace.'),
+    'pilot_checklist_incomplete': ('user_action', 'The pilot checklist is incomplete. The owner must verify actual project and Studio evidence before its flags can be true.'),
     'comments_disabled': ('inspect', 'Comments are disabled on this video. Reconnecting does not enable them; do not change video settings without owner approval.'),
     'target_unavailable': ('correct_input', 'Verify the requested target and account before another read.'),
     'request_rejected': ('correct_input', 'Review supported arguments and target before another request.'),
@@ -74,6 +78,8 @@ _CATALOG = {
     'persistence_failed': ('repair_storage', 'Preserve verified observations and repair local persistence before collecting again.'),
     'unsupported_operation': ('unsupported', 'This integration does not support the requested operation.'),
     'account_not_configured': ('user_action', 'Ask the owner to select and authorize the intended account; never infer one.'),
+    'workspace_unavailable': ('inspect_workspace', 'Cannot read the selected workspace. Check --root or SOCIALCLI_ROOT and local file permissions.'),
+    'brand_not_found': ('correct_input', 'The named brand is not in the selected workspace. Check --brand and --root or SOCIALCLI_ROOT; do not select another brand automatically.'),
     'invalid_input': ('correct_input', 'Review the supported arguments and explicit workspace.'),
     'installation_access_required': ('sign_in', 'Ask the owner to sign in to SocialCli again.'),
     'invalid_report_options': ('correct_input', 'Review the report date, window, item limit and platform.'),
@@ -102,6 +108,7 @@ def error_for_code(code: str, *, read_only: bool = True) -> dict:
 
 def error_document(exc: BaseException, *, read_only: bool) -> dict:
     import httpx
+    from socialctl.brands import WorkspaceUnavailable, BrandNoEncontrada, AccountsInvalido, NombreDeMarcaInvalido
     from socialctl.read_budget import LocalConfigurationError
     from socialctl.auth import AuthError
     from socialctl.read_budget import ReadDeadlineExceeded, ReadResponseTooLarge
@@ -131,6 +138,11 @@ def error_document(exc: BaseException, *, read_only: bool) -> dict:
         code = 'operation_uncertain'
     elif isinstance(exc, (AuthError, YouTubeManagementError, ChangeError, ResourceError, CommentError, MetaError, ReadError)) and getattr(exc, '_socialcli_error_code', None) is not None:
         code = exc._socialcli_error_code
+    elif isinstance(exc, YouTubeDataBusy): code = 'local_data_busy'
+    elif isinstance(exc, YouTubeDataCleanupError): code = 'storage_failure'
+    elif isinstance(exc, WorkspaceUnavailable): code = 'workspace_unavailable'
+    elif isinstance(exc, BrandNoEncontrada): code = 'brand_not_found'
+    elif isinstance(exc, (AccountsInvalido, NombreDeMarcaInvalido)): code = 'invalid_input'
     elif isinstance(exc, ReadDeadlineExceeded): code = 'read_deadline'
     elif isinstance(exc, ReadResponseTooLarge): code = 'response_too_large'
     elif isinstance(exc, KeyboardInterrupt): code = 'read_interrupted'
@@ -157,8 +169,7 @@ def error_document(exc: BaseException, *, read_only: bool) -> dict:
                 'configuration_missing': 'account_not_configured'}.get(exc.code, 'target_validation_failed')
     elif isinstance(exc, ResourceError): code = 'target_validation_failed'
     elif isinstance(exc, ChangeError): code = 'operation_rejected'
-    elif isinstance(exc, YouTubeDataBusy): code = 'local_data_busy'
-    elif isinstance(exc, (OSError, YouTubeDataCleanupError)): code = 'storage_failure'
+    elif isinstance(exc, OSError): code = 'storage_failure'
     elif isinstance(exc, ValueError): code = 'invalid_local_state'
     else: code = 'operation_failed'
     result = error_for_code(code,read_only=read_only)
@@ -189,7 +200,7 @@ def safe_diagnostic(value):
         'write_state': {'not_started', 'unknown', 'accepted'},
         'content_write_state': {'not_started'},
         'reason': {'thread_unverifiable', 'thread_identity_mismatch', 'thread_total_unverifiable', 'comment_binding_mismatch', 'parent_mismatch', 'replies_not_allowed', 'incomplete_reply_list', 'readback_mismatch'},
-        'provider_reason': {'commentsDisabled', 'quotaExceeded', 'dailyLimitExceeded', 'rateLimitExceeded', 'userRateLimitExceeded', 'insufficientPermissions', 'forbidden', 'authError', 'invalidValue', 'videoNotFound', 'commentNotFound', 'commentThreadNotFound', 'processingFailure', 'operationNotSupported'},
+        'provider_reason': {'playlistNotFound', 'playlistItemNotFound', 'playlistItemsNotAccessible', 'commentsDisabled', 'quotaExceeded', 'dailyLimitExceeded', 'rateLimitExceeded', 'userRateLimitExceeded', 'insufficientPermissions', 'forbidden', 'authError', 'invalidValue', 'videoNotFound', 'commentNotFound', 'commentThreadNotFound', 'processingFailure', 'operationNotSupported'},
     }
     clean = {key: val for key, val in value.items()
              if key in allowed and isinstance(val, str) and val in allowed[key]}

socialcli-0.3.3/socialctl/agent_guide.py

@@ -0,0 +1,25 @@
+"""Topic selection keeps advanced contracts available without bloating bootstrap."""
+from importlib.resources import files
+import importlib.metadata
+import re
+
+TOPICS={
+    'setup':('Workspace and YouTube outcome recovery','What agents can do','Install the reviewed release','Authorize the installation, then the social account','Persist and recover','Publication gate','Explicit approval and preflight'),
+    'publish':('Publication gate','Temporary Instagram media','Canonical publishing workflow','Check supplied media locally','Explicit approval and preflight'),
+    'schedule':('Preparing YouTube schedules and interpreting inventory','Publication gate','Temporary Instagram media','Scheduling and temporary media','Native scheduling input examples (offline)','Explicit approval and preflight'),
+    'inbox':('Preparing YouTube schedules and interpreting inventory','Workspace and YouTube outcome recovery','Publication gate','Read metrics and prepare engagement','Read diagnostics','Comment API evidence and limits','Explicit approval and preflight','Resumable batches and reply context','Purged reply history'),
+    'errors':('Workspace and YouTube outcome recovery','Persist and recover','Recovery and error actions','Read diagnostics','Comment API evidence and limits','Explicit approval and preflight','Resumable batches and reply context','Purged reply history'),
+    'permissions':('Installation connection access',),
+}
+
+
+def guide(topic):
+    if topic not in TOPICS and topic!='all':
+        raise ValueError('Choose a guide topic: '+', '.join(TOPICS)+', all.')
+    full=files('socialctl.ui').joinpath('assets/agent-manual.md').read_text(encoding='utf-8')
+    full = full.replace('{{SOCIALCLI_VERSION}}', importlib.metadata.version('socialcli'))
+    if topic=='all':return full
+    sections=re.split(r'(?=^## )',full,flags=re.MULTILINE)
+    chosen=[section for section in sections if any(section.startswith('## '+heading) for heading in TOPICS[topic])]
+    return ('# SocialCli agent guide: '+topic+'\n\n'+''.join(chosen)+
+            '\nNext: socialcli agent-guide publish; socialcli agent-guide schedule; socialcli agent-guide inbox; socialcli agent-guide errors; socialcli agent-guide permissions; socialcli agent-guide all.\n')

{socialcli-0.3.2 → socialcli-0.3.3}/socialctl/brands.py

@@ -21,6 +21,13 @@ class BrandNoEncontrada(Exception):
     """The requested brand directory does not exist."""
 
 
+class WorkspaceUnavailable(OSError):
+    """The selected workspace cannot be inspected safely."""
+
+    def __init__(self):
+        super().__init__('Cannot read the selected workspace. Check --root or SOCIALCLI_ROOT and local file permissions.')
+
+
 class BrandYaExiste(Exception):
     """The requested brand directory already exists."""
 
@@ -148,13 +155,28 @@ def crear_brand(raiz_social: Path, nombre: str) -> Brand:
 
 
 def cargar_brand(raiz_social: Path, nombre: str, *, cleanup: bool = True) -> Brand:
+    try:
+        brand = _read_brand(raiz_social, nombre)
+    except (OSError, RuntimeError) as exc:
+        raise WorkspaceUnavailable() from None
+    if cleanup:
+        from socialctl.youtube_data import enforce_youtube_data
+        enforce_youtube_data(brand.raiz)
+    return brand
+
+
+def _read_brand(raiz_social: Path, nombre: str) -> Brand:
     """Load an existing explicitly named brand."""
     raiz = _validar_nombre_de_marca(raiz_social, nombre)
     if not raiz.is_dir():
-        disponibles = sorted(
-            p.name for p in raiz_social.iterdir()
-            if p.is_dir() and (p / "brand.md").exists()
-        )
+        disponibles = []
+        for p in raiz_social.iterdir():
+            try:
+                if p.is_dir() and (p / 'brand.md').exists():
+                    disponibles.append(p.name)
+            except OSError:
+                continue
+        disponibles.sort()
         raise BrandNoEncontrada(
             f"brand does not exist: '{nombre}' in {raiz_social}. "
             f"Available brands: {', '.join(disponibles) or 'none'}"
@@ -183,9 +205,6 @@ def cargar_brand(raiz_social: Path, nombre: str, *, cleanup: bool = True) -> Bra
                 f"'{fichero_cuentas}' must contain an account mapping (key: value); received {type(contenido_cuentas).__name__}"
             )
 
-    if cleanup:
-        from socialctl.youtube_data import enforce_youtube_data
-        enforce_youtube_data(raiz)
     return Brand(
         nombre=nombre,
         raiz=raiz,

{socialcli-0.3.2 → socialcli-0.3.3}/socialctl/cli.py

@@ -149,13 +149,15 @@ def show_delivery_options(
 ):
     """Explain delivery modes and limits; does not authenticate or send media."""
     from socialctl.delivery_options import delivery_options
-    result = delivery_options(_cargar_marca(root, brand_nombre))
-    if json_output:
-        typer.echo(json.dumps(result, indent=2))
-    else:
-        typer.echo('SocialCli does not store customer media on its SaaS server.')
-        for platform, row in result['platforms'].items():
-            typer.echo(f"{platform}: {row['selected_delivery']} — {row['instruction']}")
+    from socialctl.operation_output import OperationOutput
+    with OperationOutput(json_output, read_only=True) as output:
+        result = delivery_options(output.brand(root, brand_nombre))
+        if json_output:
+            typer.echo(json.dumps(result, indent=2))
+        else:
+            typer.echo('SocialCli does not store customer media on its SaaS server.')
+            for platform, row in result['platforms'].items():
+                typer.echo(f"{platform}: {row['selected_delivery']} — {row['instruction']}")
 
 
 def _show_version(value: bool):

{socialcli-0.3.2 → socialcli-0.3.3}/socialctl/connections/account_cli.py

@@ -355,13 +355,13 @@ def attach(platform:Platform,brand_name:str=typer.Option(...,'--brand'),root:Pat
                     client.request('GET','/api/saas/v1/connections/'+opaque(previous['connection_id']),
                         secret=keychain.get(brand,platform,previous))
                 except ServiceRejected as exc:
-                    # Browser revocation removes capabilities, so their status
-                    # becomes 404. This explicit attach still authenticates the
+                    # Browser revocation removes capabilities (404); a new
+                    # owner grant replaces them (409). Explicit attach authenticates the
                     # current installation, requires its owner-approved platform
                     # and existing grant, and checks the exact old account below.
                     if (exc.status,exc.code) not in {
                             (401,'installation_revoked'),(401,'installation_expired'),
-                            (404,'connection_unavailable')}:
+                            (404,'connection_unavailable'),(409,'connection_replaced')}:
                         raise
                 else:raise ValueError('A local connection already exists. Review it before replacing it.')
             result=client.request('POST','/api/saas/v1/installations/'+opaque(saved['connection_id'])+'/attach',

{socialcli-0.3.2 → socialcli-0.3.3}/socialctl/inbox.py

@@ -206,7 +206,14 @@ def sync_brand_inbox(brand,*,since,budget,only=None):
                         if inventory.get('failure_class'):
                             errors.append({'platform': 'youtube',
                                 **inventory.get('error_detail', {'code': 'read_partial', 'message': 'Video inventory incomplete.'})})
-                        media=[v['remote_id'] for v in InventoryStore(brand,platform,account).list_items() if v.get('last_sync_id')==inventory['sync_id']]
+                        from socialctl.inventory import youtube_target_context
+                        saved_media = {v['remote_id']: v for v in inventory_store.list_items()}
+                        media = [ident for ident, value in saved_media.items() if value.get('last_sync_id') == inventory['sync_id']]
+                        for ident in inventory.get('missing_resource_ids', []):
+                            errors.append({'platform': 'youtube', 'media_id': ident, 'code': 'target_unavailable',
+                                'message': 'YouTube did not return this video in the inventory detail read. Its current visibility and comment coverage are unknown.',
+                                'availability_reason': 'not_returned_by_youtube', 'stage': 'inventory_details',
+                                **youtube_target_context(saved_media.get(ident))})
                         complete=inventory['complete'] and inventory['details_complete']
                         client=YouTubeInboxClient(brand,http)
                         for ident in media:
@@ -224,7 +231,8 @@ def sync_brand_inbox(brand,*,since,budget,only=None):
                             observed_keys.update(store.key(i) for i in items)
                             row['scopes'].append({'media_id':ident,'filter':'published','complete':ok})
                             complete=complete and ok
-                            errors.extend({**_problem_document(e),'platform':platform.value,'media_id':ident} for e in problems)
+                            errors.extend({**_problem_document(e),'platform':platform.value,'media_id':ident,
+                                **youtube_target_context(saved_media.get(ident))} for e in problems)
                     else:
                         meta=MetaClient(brand,platform,http)
                         listing=meta.content_list('posts' if platform is Platform.FACEBOOK else 'media',for_comments=True)

{socialcli-0.3.2 → socialcli-0.3.3}/socialctl/inventory.py

@@ -146,7 +146,10 @@ def sync_content(brand, platform, client, *, max_pages=20, resume=False):
             run["failure_class"] = "page_limit"
         run["updated_at"] = now()
         state["sync"] = run
+        if platform is Platform.YOUTUBE:
+            verified_video_deletions(brand, state)
         store.save(state)
+        deleted_count = sum(row.get('presence') == 'deleted_verified' for row in state['items'].values())
         return {"version": 1, "brand": brand.nombre, "platform": platform.value,
                 "account_id": probe.account_id, "identity": identity, "sync_id": run["id"],
                 "complete": run["complete"], "failure_class": run["failure_class"],
@@ -156,4 +159,48 @@ def sync_content(brand, platform, client, *, max_pages=20, resume=False):
                 "resume_available": run["resumable"], "pages": run["pages"],
                 "observed_items": len(run["seen_ids"]), "stored_items": len(state["items"]),
                 "missing_resource_ids": run["missing_resource_ids"], "deletion_proven": False,
+                "verified_deleted_items": deleted_count, "retained_items": len(state["items"]) - deleted_count,
+                "deletion_scope": "Per-item verified deletion evidence; absence from sync alone is not proof",
                 "source": run.get("source"), "updated_at": run["updated_at"]}
+
+
+def youtube_target_context(row):
+    """Last observed metadata is context, never a current visibility inference."""
+    row = row or {}
+    status = row.get('observed_status')
+    status = status if isinstance(status, dict) else {}
+    return {'video_title': row.get('title'), 'scheduled_publish_at': status.get('publishAt'),
+            'last_observed_privacy': status.get('privacyStatus'),
+            'metadata_observed_at': row.get('last_observed_at'),
+            'metadata_basis': 'last_inventory_observation' if row else 'unavailable'}
+
+
+def verified_video_deletions(brand, state):
+    """Join durable exact deletion receipts without erasing historical inventory."""
+    from socialctl.management.owned_changes import OwnedStore
+    store = OwnedStore(brand.raiz)
+    count = 0
+    for path in store.root.glob('*.json'):
+        try:
+            change = store.load(path.stem)
+        except (ValueError, OSError):
+            continue
+        if (change.target_brand != brand.nombre or change.target_account != state['account_id']
+                or change.edit.get('action') != 'video-delete' or change.resource != 'videos'
+                or change.status != 'verified' or change.verified is not True
+                or not change.receipt or change.receipt.get('http_status') != 204):
+            continue
+        events = [event for event in change.journal if event.get('event') == 'delete_readback'
+                  and event.get('absent_observed') is True]
+        row = state['items'].get(change.target_id)
+        if not events or row is None:
+            continue
+        # A fresh provider observation wins over an older local deletion receipt.
+        if row.get('last_sync_id') == (state.get('sync') or {}).get('id'):
+            continue
+        row.update(presence='deleted_verified', deletion_proven=True,
+            deletion_evidence={'change_id': change.id, 'fingerprint': change.fingerprint,
+                'verified_at': change.updated_at.isoformat(), 'http_status': 204,
+                'basis': 'receipt_and_exact_id_absence'})
+        count += 1
+    return count

{socialcli-0.3.2 → socialcli-0.3.3}/socialctl/inventory_cli.py

@@ -40,8 +40,10 @@ def guarded(operation, json_output):
         data = operation()
     except ReadError as exc:
         data = {"version": 1, "failure_class": exc.code}
-    except Exception:
-        data = {"version": 1, "failure_class": "local_state_invalid"}
+    except Exception as exc:
+        from socialctl.agent_errors import error_document
+        data = {"version": 1, "failure_class": "local_state_invalid",
+                "status": "error", "error": error_document(exc, read_only=True)}
     emit(data, json_output)
     if data.get("failure_class"):
         raise typer.Exit(1)

{socialcli-0.3.2 → socialcli-0.3.3}/socialctl/management/batches.py

@@ -18,7 +18,7 @@ from socialctl.management.metadata_parts import KINDS, MetadataEdit, editable_pa
 from socialctl.management.youtube import (YouTubeManagementError, YouTubeUpdateConflict,
     YouTubeUpdateRejected)
 from socialctl.management.youtube_metadata import same_metadata_snapshot
-from socialctl.management.snippet_readback import snippet_mismatch_fields
+from socialctl.management.snippet_readback import snippet_mismatch_fields, snippet_readback_evidence
 
 
 class BatchFile(BaseModel):
@@ -172,7 +172,7 @@ def _event(op, event, **details):
     op.journal.append({"at": now_utc().isoformat(), "event": event, **details})
 
 
-def _mismatch_paths(current, expected):
+def _mismatch_paths(current, expected, *, before=None):
     """Return bounded field names without raw bodies or values."""
     mismatches = []
     parts = editable_parts(current.resource)
@@ -193,7 +193,9 @@ def _mismatch_paths(current, expected):
             except (AttributeError, TypeError, ValueError):
                 pass
         if part == "snippet":
-            mismatches.extend(f"snippet.{field}" for field in snippet_mismatch_fields(actual, wanted))
+            fields = (snippet_readback_evidence(actual, wanted, before=before.get('snippet', {}))['mismatch_fields']
+                      if before is not None else snippet_mismatch_fields(actual, wanted))
+            mismatches.extend(f"snippet.{field}" for field in fields)
             continue
         for field in sorted(set(actual) | set(wanted)):
             if field not in actual or field not in wanted or actual[field] != wanted[field]:
@@ -217,9 +219,9 @@ def _apply_operation(client, store, batch, op):
         store.save(batch)
         return
     if op.status in {"applying", "uncertain"}:
-        mismatches = _mismatch_paths(current, op.after)
+        mismatches = _mismatch_paths(current, op.after, before=op.before)
         op.status = "manual_review" if mismatches else "applied"
-        _event(op, "reconciled_read_only", mismatch_paths=", ".join(mismatches))
+        _event(op, "reconciled_read_only", mismatch_paths=", ".join(mismatches), provider_added_fields=_added_fields(current, op))
         store.save(batch)
         return
     if not same_metadata_snapshot(op.observed, current.resource, allow_etag_only=True):
@@ -267,9 +269,9 @@ def _apply_operation(client, store, batch, op):
         for attempt in readback_attempts():
             try:
                 verified = client.inspect(op.video_id)
-                mismatches = _mismatch_paths(verified, op.after)
+                mismatches = _mismatch_paths(verified, op.after, before=op.before)
                 op.status = "uncertain" if mismatches else "applied"
-                _event(op, "read_back_" + op.status, mismatch_paths=", ".join(mismatches), attempt=str(attempt))
+                _event(op, "read_back_" + op.status, mismatch_paths=", ".join(mismatches), attempt=str(attempt), provider_added_fields=_added_fields(verified, op))
                 store.save(batch)
                 if not mismatches:
                     break
@@ -333,3 +335,36 @@ def prepare_restore(client, store: BatchStore, original_id: str) -> Batch:
             operations.append(_operation(client, edit, resets=resets))
     return _save_new(store, _batch(client, operations, {str(source): source_hash},
         restored_from=original_id, unavailable=unavailable))
+
+
+def _added_fields(current, op):
+    if 'snippet' not in op.after:
+        return ''
+    evidence = snippet_readback_evidence(editable_parts(current.resource)['snippet'],
+        op.after['snippet'], before=op.before.get('snippet', {}))
+    return ', '.join(evidence['provider_added_fields'])
+
+
+def reconcile_batch(client, store, batch_id):
+    """Recover only attempted children; never execute untouched batch members."""
+    with store.apply_lock(batch_id):
+        batch = store.load(batch_id)
+        _bound(client, batch)
+        for op in batch.operations:
+            if op.status not in {'applying', 'uncertain', 'manual_review'}:
+                continue
+            if not any(event.get('event') == 'write_intent' for event in op.journal):
+                _event(op, 'recovery_blocked', reason='write_intent_missing')
+                continue
+            try:
+                current = client.inspect(op.video_id)
+                mismatches = _mismatch_paths(current, op.after, before=op.before)
+                op.status = 'manual_review' if mismatches else 'applied'
+                _event(op, 'reconciled_read_only', mismatch_paths=', '.join(mismatches),
+                       provider_added_fields=_added_fields(current, op))
+            except (YouTubeManagementError, ChangeError, OSError) as exc:
+                from socialctl.agent_errors import error_document
+                _event(op, 'reconciliation_failed', error_detail_json=json.dumps(
+                    error_document(exc, read_only=True), sort_keys=True))
+            store.save(batch)
+        return batch

{socialcli-0.3.2 → socialcli-0.3.3}/socialctl/management/changes.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from socialctl.management.snippet_readback import same_snippet_readback, snippet_mismatch_fields, readback_attempts
+from socialctl.management.snippet_readback import same_snippet_readback, snippet_mismatch_fields, readback_attempts, snippet_readback_evidence
 
 import fcntl
 import hashlib
@@ -445,14 +445,15 @@ def apply_youtube_change(
                 if detail['retryable']:
                     continue
                 break
-            mismatch = snippet_mismatch_fields(youtube.editable_snippet(verified), change.after)
+            evidence = snippet_readback_evidence(youtube.editable_snippet(verified), change.after, before=change.before)
+            mismatch = evidence['mismatch_fields']
             if not mismatch:
                 break
             _append(change, 'verification_mismatch', fields=mismatch, attempt=attempt)
             store.save(change)
         else:
             verified = None
-        if verified is None or not same_snippet_readback(youtube.editable_snippet(verified), change.after):
+        if verified is None or snippet_readback_evidence(youtube.editable_snippet(verified), change.after, before=change.before)['mismatch_fields']:
             change.status = 'uncertain'
             store.save(change)
             error = ChangeError('uncertain outcome: YouTube accepted PUT but complete readback was not verified; reconcile this ChangeSet without repeating the write')
@@ -463,38 +464,59 @@ def apply_youtube_change(
 
         change.status = "applied"
         change.verified = True
-        _append(change, "verified_applied", etag=verified.etag)
+        _append(change, "verified_applied", etag=verified.etag, provider_added_fields=evidence["provider_added_fields"])
         store.save(change)
         return change
 
 
 def _reconcile(
-    youtube: YouTubeManagementClient, store: ChangeStore, change: ChangeSet
+    youtube: YouTubeManagementClient, store: ChangeStore, change: ChangeSet, *, return_unresolved=False
 ) -> ChangeSet:
     """Reread only; never call update when resuming an uncertain attempt."""
     try:
         current = youtube.inspect(change.video_id)
     except YouTubeManagementError as exc:
-        _append(change, "reconciliation_failed", error=str(exc))
+        from socialctl.agent_errors import error_document
+        detail = error_document(exc, read_only=True)
+        _append(change, "reconciliation_failed", error=detail['message'], error_detail=detail)
         store.save(change)
+        if return_unresolved:
+            return change
         raise ChangeError(
             "outcome remains uncertain: read-only reconciliation failed"
         ) from None
 
     snippet = youtube.editable_snippet(current)
-    if same_snippet_readback(snippet, change.after):
+    evidence = snippet_readback_evidence(snippet, change.after, before=change.before)
+    if not evidence['mismatch_fields']:
         change.status = "applied"
         change.verified = True
-        _append(change, "reconciled_applied", etag=current.etag)
+        _append(change, "reconciled_applied", etag=current.etag, provider_added_fields=evidence["provider_added_fields"])
         store.save(change)
         return change
 
     change.status = "manual_review"
     change.verified = False
     event = "reconciled_still_before" if _same_snippet(snippet, change.before) else "reconciled_diverged"
-    _append(change, event)
+    _append(change, event, mismatch_fields=evidence['mismatch_fields'],
+            provider_added_fields=evidence['provider_added_fields'])
     store.save(change)
+    if return_unresolved:
+        return change
     raise ChangeError(
         "uncertain PUT requires manual review; reconciliation was read-only "
         "and did not repeat the write"
     )
+
+
+def reconcile_youtube_change(youtube, store, change_id):
+    """Explicit recovery of an attempted V1 write, including manual review."""
+    with store.apply_lock(change_id):
+        change = store.load(change_id)
+        if youtube.configured_channel_id != change.target_account:
+            raise ChangeError('configured account no longer matches ChangeSet')
+        if change.status not in {'applying', 'uncertain', 'manual_review'}:
+            return change
+        if not any(event.get('event') == 'write_intent' for event in change.journal):
+            raise ChangeError('read-only recovery requires a recorded write intent')
+        return _reconcile(youtube, store, change, return_unresolved=True)

{socialcli-0.3.2 → socialcli-0.3.3}/socialctl/management/cli.py

@@ -225,3 +225,36 @@ register_community(content_app, DEFAULT_ROOT)
 from socialctl.metricas.analytics_cli import register as register_analytics
 
 register_analytics(content_app, DEFAULT_ROOT)
+
+
+@changes_app.command('reconcile')
+def changes_reconcile(change_id: str, brand: str = typer.Option(..., '--brand'),
+                      root: Path = typer.Option(DEFAULT_ROOT, '--root'),
+                      json_output: bool = typer.Option(False, '--json')):
+    """Read-only V1/V2 metadata recovery. Never starts pending operations."""
+    from socialctl.management.changes import reconcile_youtube_change
+    from socialctl.management.batches import reconcile_batch
+    from socialctl.management.youtube_metadata import YouTubeMetadataClient
+    from socialctl.operation_output import OperationOutput
+    with OperationOutput(json_output, read_only=True):
+        selected = cargar_brand(root, brand)
+        single_store, batch_store = ChangeStore(selected.raiz), BatchStore(selected.raiz)
+        is_batch = batch_store.path_for(change_id).exists()
+        if is_batch and single_store.path_for(change_id).exists():
+            raise ChangeError('ambiguous ChangeSet ID in both metadata stores')
+        with make_http_client() as http:
+            if is_batch:
+                result = reconcile_batch(YouTubeMetadataClient(selected, http), batch_store, change_id)
+                verified = [op.id for op in result.operations if op.status == 'applied']
+                untouched = [op.id for op in result.operations if op.status == 'pending']
+                unresolved = [op.id for op in result.operations if op.id not in verified + untouched]
+            else:
+                result = reconcile_youtube_change(YouTubeManagementClient(selected, http), single_store, change_id)
+                verified = [result.id] if result.status == 'applied' and result.verified else []
+                untouched = [result.id] if result.status == 'proposed' else []
+                unresolved = [] if verified or untouched else [result.id]
+        payload = result.model_dump(mode='json')
+        payload['verification_summary'] = {'verified_ids': verified, 'unresolved_ids': unresolved, 'untouched_ids': untouched}
+        typer.echo(_json(payload))
+        if unresolved or untouched:
+            raise typer.Exit(1)

{socialcli-0.3.2 → socialcli-0.3.3}/socialctl/management/community_changes.py

@@ -61,6 +61,11 @@ def baseline(client, edit):
     action = edit.action
     if action in {"add", "reply"}:
         video = client.inspect(edit.video_id)
+        if getattr(video, 'status', {}).get('privacyStatus') == 'private':
+            exc = ResourceError('YouTube disables comments on private videos. No settings were changed.')
+            exc._socialcli_error_code = 'private_video_comments_disabled'
+            exc._socialcli_diagnostic = {'source': 'local', 'stage': 'baseline_check', 'write_state': 'not_started'}
+            raise exc
         before = {"video_id": edit.video_id, "owner": video.channel_id}
         if action == "reply":
             thread = client.thread(edit.video_id, edit.thread_id)